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PREFACE 



Purpose 



The BiiN^IOS Guide shows you how to use the services provided by the BiiN™ operating 
system. 

Audience 

This manual is intended for both applications programmers and systems programmers. Such 
programmers use the OS to create: 

• Object-oriented applications that provide data protection, data integrity, program 
modularity, and extensibility 

• Applications that manage record-structured files 

• Interactive applications that use windows, menus, commands, messages, and forms 

• Concurrent applications using multiple processes, including real-time applications 

• Distributed applications that provide services at multiple nodes in a network 

• New device drivers. 

Organization 

The BiiN™/OS Guide is divided into eleven major parts: 

I, Introduction Introduces the OS and how to make system calls. 

n. Support Services 

Fundamental services for message handling, text and string handling, using 
system objects, and transaction processing. 

in. Directory Services 

Hierarchical directories, lists of directories, user IDs, and authority lists. 

IV. I/O Services Standard I/O access methods and I/O devices. 

V. Human Interface Services 

Programming interactions with the user: command input, menus, forms, 
and reports. 

VI. Program Services 

Concurrent programming and scheduling. 

Vn. Type Manager Services 

Creating new services using new object types. 

Vm. Distribution Services 

Creating services that exist at multiple nodes in a network and that com- 
municate to provide distributed services. 
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IX. Device Services ^ > .cj 

Creating device managers and device drivers. 

X. Appendixes Complete listings of examples excerpted in this manual, and a Glossary of 

terms used in this nialiu^. 

Index 

The chapters in each part describe major programming areas such as "Using Basic I/O" or 
"Building Concurrent Programs." A chapter may contain basic concepts about the program- 
ming area, specific programming techniques, or both. Many techniques are illustrated with 

TM 

excerpts from BiiN Ada examples. Iifte44n Appendix X-A. 



Related Publications 



This manual does not provide detailed reference information for system calls. For descriptions 



tTM 



of system calls, see the BiiN I OS Reference Manual. All OS programmers should also see the 
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"Files, Modules, and Views" appendix in the BiiN /OS Reference Manual for important infor- 
mation regarding finding OS files and compiling and linking programs that use the OS. 

The following manuals may be of use to you while programming with the OS: 

BiiN™ Systems Overview 

High-level description of BiiN™ systems. 

Getting Started with BiiN™ Systems 

How to log in, basic interactive commands, and how to set up your en- 
vironment. 

TM 

BiiN Systems Programmer's Guide 

Languages and tools used to program in the BiiN™ environment, and some 
application examples. 

BiiN™ Ada User's Guide 

User's guide for the BiiN™ Ada programming language. 

BiiN™ Ada Language Reference Manual 

TM 

Language reference for the BiiN Ada programming language. 

BiiN™ C Programming Manual 

Programmer's manual for the BiiN™ C programming language. This 
manual includes a chapter on using the OS from C programs. 

BiiN™lOS Reference Manual 

Package descriptions for using the OS. 



Notation 



glossary term Tenns being defined or used for the first time are in italic font, and can be 
found in the Glossary. 

Package_Name BiiN™ Ada reserved words and OS package and call names are in 
typewriter font. 

The following abbreviations are used throughout this manual: 

K 2^^ = 1 ,024. For example, IK bytes equals 1 ,024 bytes. 
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2^0 = 1,048,576. For example, IM bytes equals 1,048,576 bytes. 

2^0= 1,073,741,854. For example, IG bytes equals 1,073,741,824 bytes. 

Access Descriptoi^,,a system object pointer. An AD references a system 
object. 

Storage Resource Object, which defines memory storage available for a 
job or node. 

Type Definition Object, which defines an object's type. Each object 
references the TDO focits type. 

General Data Proces^6r, 'a central processing unit in a BiiN™ node. 



In examples of BiiN commands, the user's input is 
responses are not. For example: 

clex-> 



boxed 



and the system's prompts and 



eg hello. c 



clex-> 
clex-> 



link hello. obj :output=hello 



hello 



Hello, world! 
clex-> 

This manual uses the following notation to describe syntax: 

name ;;= syntax-exp 

A syntactic equation, indicating that the word on the left side symbolizes 
the expression on the right side. 

name Words in italic font are names for other expressions. A name containing 

hyphens, such as basic-type-specifier, should be considered a single word. 

name Words and symbols in typewriter font are literal characters and 

character strings. 

a-z Specifies any single character >= a and <= z in the ASQI collating se- 

quence. 

Al B OR: Specifies a string that matches ^4 or a string that matches B. 

[A] Brackets surround an optional sjmtactic element. 

A... Ellipses indicate that one or more elements can be used. 

(A) Parentheses group items to specify an order of evaluation. 

An example of syntax notation: 



appetizer .;= 

[ soup-type J soup / 
vegetable almondine/ 
chips /& salsa 7 

soup-type ::= 

meat noodle / 
cream of vegetable 

meat ::= 

chicken /beef 

vegetable ::= 

potato/ cauliflower/broccoli 
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The following strings are valid appetizers, according to the above syntax: 

chicken noodle soup 
cream of broccoli soup 
broccoli almondine 
chips 



vi Preface 



PRELIMINARY 



CONTENTS 



Part I. Introduction. 



Chapter 1 . Concepts 



tTM 



I-l.l BiiN OS Functionality 1-1-2 

1-1.2 Transparent Multiprocessing with Multiple Processors 1-1-2 

1-1.3 Fault-Tolerant Computing 1-1-5 

1-1.4 Transaction Processing and DBMS Support 1-1-7 

1-1.5 Computing in a Distributed Environment 1-1-8 

1-1.6 Support for UNIX and ISO Standards 1-1-8 

1-1.7 Services for High-Function Applications 1-1-9 

1-1.8 Transparent Resource Management for Easy Programming I-l-lO 

1-1.9 Getting Real Time Data I-l-lO 

I-l.lO System Administration and the Clearinghouse I-l-ll 

I-l.ll BiiN™ OS Architecture M-12 

1-1.12 Some Basics 1-1-13 

1-1.12.0.1 What Is A System Object? 1-1-14 

1-1.12.0.2 How Are System Objects Protected? 1-1-15 



Chapter 2. Service Areas and Services 



1-2.1 Service Areas 1-2-3 

1-2.2 Support Services 1-2-3 

1-2.2.1 Utility Service 1-2-3 

1-2.2.2 Object Service 1-2-4 

1-2.2.3 Transaction Service 1-2-4 

1-2.2.4 Message Service 1-2-4 

1-2.3 Directory Services 1-2-5 

1-2.3.1 Naming Service 1-2-5 

1-2.3.2 Protection Service 1-2-5 

1-2.4 I/O Services 1-2-5 

1-2.4.1 Basic I/O Service 1-2-6 

1-2.4.2 Character Terminal Service 1-2-6 

1-2.4.3 Print Service 1-2-6 

1-2.4.4 Spool Service 1-2-6 

1-2.4.5 Filing Service 1-2-6 

1-2.4.6 Database Support Service 1-2-7 

1-2.4.7 Data Definition Service 1-2-7 

1-2.4.8 Volume Set Service 1-2-7 

1-2.4.9 Basic Disk Service 1-2-7 

1-2.4.10 Basic Streamer Service 1-2-8 

1-2.4.11 Null Device Service 1-2-8 



Contents vii 



rjcvjci^iivij.i'^rt.K. I 



1-2.5 Human Interface Services 1-2-8 

1-2.5.1 Command Service 1-2-8 

1-2.5.2 Form Service 1-2-8 

1-2.5.3 Report Service 1-2-8 

1-2.6 Program Services 1-2-9 

1-2.6.1 Concurrent Programming Service 1-2-9 

1-2.6.2 Scheduling Service 1-2-9 

1-2.6.3 Timing Service 1-2-10 

1-2.6.4 Resource Service 1-2-10 

1-2.6.5 Program Building Service 1-2-10 

1-2.6.6 Monitor Service 1-2-11 

1-2.7 Type Manager Services 1-2-1 1 

1-2.7.1 TM Object Service 1-2-11 

1-2.7.2 TMTransaction Service 1-2-11 

1-2.7.3 TM Concurrent Programming Service 1-2-12 

1-2,7.4 Configuration Service 1-2-12 

1-2.7.5 Custom Naming Service 1-2-12 

1-2.7.6 Backup Service 1-2-12 

1-2.7.7 Distribution Services 1-2-13 

1-2.7.8 Qearinghouse Service 1-2-13 

1-2.7.9 RPC Service 1-2-13 

1-2.7.10 Transport Service 1-2-13 

1-2.8 Device Services 1-2-14 

1-2.8.1 Device Driver Service 1-2-14 

1-2.8.2 Shared Queue Service 1-2-15 

1-2.8.3 Asynchronous Communication Service 1-2-15 

1-2.8.4 Mass Storage Service 1-2-15 

1-2.8.5 SCSIService 1-2-15 

1-2.8.6 Subnet Service 1-2-15 

1-2.8.7 HDLC Service 1-2-16 

1-2.8.8 LAN Service 1-2-16 



Chapter 3- Ada Programming Techniques 



1-3.1 Concepts 1-3-2 

1-3. 1.1 Working with Pointers 1-3-2 

1-3.1.2 Common Types in the System and System_Def s Packages 1-3-2 

1-3.1.3 Standard System Exceptions 1-3-3 

1-3.1.4 Package-level and Subprogram-level Variables 1-3-3 

1-3.2 Techniques 1-3-3 

1-3.2.1 Using Unchecked Type Conversion 1-3-3 

1-3.2.2 Using Overlays as an Alternative to Unchecked T)^ Conversion 1-3-5 

1-3.2.3 Importing Operators 1-3-5 

1-3.2.4 Allocating a Buffer 1-3-6 

1-3.2.5 Recovering from Record Overflow 1-3-7 

1-3.2.6 Handling Recoverable Exceptions 1-3-8 

1-3.2.7 Using Paired CaUs 1-3-9 

1-3.3 Summary 1-3-10 



viii Contents 



PRELIMINARY 



Part II. Support Services. 



Chapter 1. Using Utility Pacloges 



II-l.l Concepts 11-1-2 

II-l.l.l StringLists II-1-2 

II-1.1.2 Texts II-1-3 

II-1.1.3 Long Integers 11-1-4 

II-1.2 Techniques II-1-4 

II-1.2.1 Using a Literal Text 11-1-4 

II-1.2.2 Declaring a Constant Text II-1-4 

II-1.2.3 Calling a Procedure with a Text Result II-1-5 

II-1.2.4 Creating a String List II-1-6 

II-1.2.5 Reading Elements from a String List II-1-6 

n-1.2.6 Using a Literal Long Integer II-1-7 

II-1.2.7 Computing with Long Integers II-1-7 

n-1.2.8 Converting Between Strings and Long Integers II-1-8 

II-1.2.9 Summary n-1-8 



Cliapter 2. Using Objects and ADs 



II-2.1 Concepts II-2-2 

n-2.1.1 Whatis an Object? n-2-2 

II-2.1.2 What is an Access Descriptor? 11-2-3 

II-2.1.3 Rep Rights Control Access to an Object's Representation II-2-4 

II-2.1.4 Type Rights Control What Type-Specific Operations are Allowed II-2-4 

II-2.1.5 Generic Objects II-2-4 

II-2.1.6 Building Type Managers That Define New Object Types II-2-4 

II-2.2 Techniques II-2-5 

II-2.2.1 Checking an Object's Type 11-2-5 

II-2.2.2 Checking Rights on an AD II-2-5 

II-2.2.3 Removing Rights From an AD II-2-5 

II-2.2.4 Creating a Generic Object 11-2-5 

II-2.2.5 Resizing an Object n-2-6 

II-2.2.6 Deallocating an Object II-2-6 

n-2.3 Summary 11-2-6 



Chapter 3. Storing Objects 



II-3.1 Concepts II-3-3 

II-3.1.1 Comparing Passive Store, Files, and Directories II-3-3 

II-3.1.2 Using Passive Store at Different Levels II-3-3 

II-3.1.3 Object Versions II-3-3 

11-3.1.4 Object Activation II-3-4 

II-3.1.5 Activation as Reincarnation II-3-5 



Contents ix 



PRELIMINARY 



II-3.1.6 AD Activation II-3-5 

II-3.1.7 Object Passivation II-3-5 

II-3.1.8 Passivation Dependencies 11-3-6 

II-3.1.9 Active-Only Objects II-3-6 

II-3.1.10 Passive Store Behavior of OS Object Types II-3-6 

n-3.1.11 Passive ADs II-3-7 

n-3.1.1 1.1 Referencing Between Active Memory and Passive Store 11-3-7 

n-3.1.11.2 Master ADs n-3-7 

II-3.1.11.3 AKas ADs n-3-8 

II-3.1.1 1.4 Restrictions on Storing Master ADs II-3-8 

II-3.1.1 1.5 Master ADs and Passive Object Lifetimes II-3-9 

n-3.1.11.6 Transferring Mastership II-3-9 

II-3.1.11.7 ObjectTrees II-3-9 

n-3.1.1 1.8 Passive ADs as Universal Identifiers II-3-10 

II-3.1.12 Passive Store Behavior of Generic Objects II-3-10 

II-3.1.13 Passive Object Characteristics II-3-10 

II-3.1.14 The Life History of a Passivated Object II-3-11 

II-3.1.15 Activation Models II-3-12 

II-3.1.15.1 Multiple Activation II-3-12 

II-3.1.15.2 Single Activation II-3-14 

II-3.1.15.3 Choosing an Activation Model II-3-14 

II-3.1.16 Transaction Support II-3-14 

II-3.1.17 The Passive Store Attribute II-3-15 

II-3.1.18 Default Passive Store Behavior II-3-15 

II-3.1.19 Type Manager Support II-3-15 

II-3.2 Techniques II-3-16 

II-3.2.1 Creating a Passive Object II-3-16 

II-3.2.2 Updating a Passive Object II-3-18 

II-3.2.3 Requesting an Update II-3-18 

II-3.2.4 Destroying a Stored Object II-3-19 

II-3.2.5 Copying a Passive Object Tree II-3-20 

II-3.2.6 Getting Passive Object Information II-3-22 

II-3.3 Summary II-3-23 



Chapter 4. Starting and Resolving Transactions 

II-4.1 Concepts II-4-2 

II-4.1.1 What Transactions Provide II-4-2 

II-4.1.2 Transaction Calls II-4-3 

II-4.1.3 Transaction Stack II-4-3 

II-4.1.4 The Default Transaction II-4-3 

II-4.1.5 Participating in Transactions II-4-3 

II-4.1.6 The Transaction Service as a Coordinator II-4-4 

II-4.1.7 Subtransactions II-4-4 

II-4.1.8 Avoiding Subtransactions II-4-4 

II-4.1.9 Rules for Using Transactions II-4-4 

II-4.1.10 Transaction Locking II-4-5 

II-4.1.1 1 Transaction Timeouts II-4-5 

II-4.1.12 Transactions and Job Termination II-4-6 

II-4.1.13 Avoiding Deadlock with Timestamp Conflicts II-4-6 



Contents 



PRELIMINARY 



II-4.1.14 Independent Transactions 11-4-6 

II-4.2 Techniques II-4-6 

II-4.2.1 Using a Transaction 11-4-6 

II-4.2.2 Avoiding Unnecessary Subtransactions II-4-7 

II-4.2.3 Using a Transaction and Recovering from Timestamp Conflicts 11-4-8 

II-4.3 Summary II-4-9 



Chapter 5. Writing IVIessages 



II-5.1 Concepts n-5-3 

II-5.1.1 Messages n-5-3 

II-5.1.2 Message Files II-5-4 

II-5.1.3 Incident Codes II-5-4 

II-5.1.4 Message Blocks II-5-5 

II-5.1.5 Message Stacks 11-5-5 

II-5.1.6 Messages and Exceptions II-5-6 

II-5.1.7 CL Variables That Affect Messages II-5-6 

II-5.1.8 How CLEX Handles Messages From Terminated Jobs II-5-7 

II-5.1.9 Message Utilities II-5-7 

II-5.1.10 History Fnes n-5-7 

n-5.2 System Error Log II-5-7 

II-5.3 Techniques II-5-7 

II-5.3.1 Defining Application Messages II-5-8 

II-5.3.1.1 In the Source File II-5-9 

n-5.3.1.2 In a Command File II-5-9 

II-5.3.1.3 Using manage .messages II-5-9 

II-5.3.2 Writing a Message II-5-10 

II-5.3.3 Associating an Incident Code With an Exception II-5-10 

II-5.3.4 Replacing an OS Exception With an Application Message II-5-1 1 

II-5.3.5 Taidng Advantage of Predefined OS Messages II-5-1 1 

II-5.3.6 Pushing a Message When Raising an Exception II-5-1 1 

II-5.3.7 Qearing the Message Stack When Handling an Exception II-5-12 

II-5.3.8 Writing a Message With Acknowledgement II-5-13 

II-5.3.9 Recording History Entries II-5-13 

II-5.3.10 Sunmiary II-5-14 



Contents xi 



rKlil-,liVUrN AK 1 



Part III. Directory Services. 



Chapter 1. Understanding Directories 



III-l.l Directory Structure IIH-2 

III-l.l.l Pathname Syntax ... ni-1-3 

IIM.1.2 Alias Entries and Master Entries ni-1-3 

in-1.1.3 Symbolic Links in-1-4 

in-1.1.4 Protecting Directories and their Contents 111-1-5 

in-1.2 The Qearinghouse: Naming in a Distributed System ni-1-5 

IIM.2.1 A Node's Default Directories III-1-8 

III-1.3 Directory Operations 111-1-8 

IIM.3.1 Retrieving Entries III-1-8 

III-1.3.2 Listing a Directory III-1-9 

in-1.3.3 Process Globals and Directories 111-1-9 

in-1.3.4 Directory Operations and Transactions III-l-lO 

III-1.3.5 Standalone Directories III-l-lO 

III-1.4 Summary ni-1-11 



Ciiapter 2. Using Directories 



III-2.1 Creating a Directory III-2-2 

III-2.2 Storing an AD in a Directory 111-2-3 

III-2.3 Retrieving a Directory Entry III-2-4 

III-2.4 Deleting a Directory Entry III-2-4 

III-2.5 Listing a Directory III-2-5 

ni-2.6 Using a Pattern to Filter a Directory Listing III-2-7 

in-2.7 Retrieving a Directory from Process Globals III-2-7 



Chapter 3. Protecting Stored Objects 



III-3.1 Concepts III-3-3 

III-3.1.1 Why Objects Need Authority-Based Protection III-3-3 

in-3.1.2 IDs Identify the Caller III-3-3 

III-3.1.2.1 What'sInanID? III-3-4 

III-3.1.3 AProcess's ID List III-3-4 

III-3.1.4 Type Rights on an ID III-3-5 

in-3.1.5 Authority Lists Specify Who Can Access Objects III-3-5 

III-3.1.6 How a Caller's Access Rights to an Object Are Evaluated III-3-6 

III-3. 1.6.1 Evaluating Access During a Retrieve III-3-6 

III-3. 1.6.2 Evaluating Access Rights During Activation III-3-8 

III-3.2 Techniques III-3-8 

III-3.2.1 Getting Information about an Object's Protection III-3-9 

III-3.2.2 Using Default Protection III-3-9 

III-3.2.3 Creating an Authority List III-3-9 



xii Contents 



FKKLIJYUINAKY 



III-3.2.4 Changing a Directory's Default Authority List III-3-10 

III-3.2.5 Changing an Object's Owner and Authority List III-3-10 

III-3.3 Summary III-3-11 



Chapter 4. Using Name Spaces 



III-4.1 Concepts m-4-2 

III-4.1.1 A Name Space is a List of Directories III-4-2 

III-4.1.2 How a Name Space References Directories III-4-3 

III-4.2 Techniques III-4-3 

III-4.2.1 Creating a Name Space III-4-3 

III-4.3 Changing a User's Command Name Space III-4-4 

III-4.4 Changing the Command Name Space within a Job or Process III-4-4 

III-4.5 Summary 111-4-5 



Chapter 5. Creating Symbolic Links 



III-5.1 Concepts in-5-2 

III-5.L1 Suppressing Link Evaluation III-5-2 

III-5.1.2 How Symbolic Links Compare with Aliases III-5-3 

III-5.1.3 Symbolic Links and Links in General III-5-3 

III-5.2 Techniques III-5-3 

III-5.2.1 Creating a Symbolic Link III-5-3 

III-5.3 Summary III-5-4 



Contents xiii 



r i\Ml,JUl.iVlJLi^AMS. I 



Part IV. I/O Services- 



Chapter 1. Understanding I/O Access Methods 

IV-l.l Devices , , . . . IV-1-2 

IV- L2 Opened Devices IV-1-2 

IV-1.3 Concurrent Access to Opened Devices IV-1-3 

IV-1.4 Device Independence IV-1-4 

IV-1.5 How Access Method Implementations Can Vary IV-1-6 

IV-1.6 BiiN Operating System I/O Access Methods IV-1-6 

IV-1.6.1 Byte Stream I/O IV-1-7 

IV-1.7 Record I/O IV-1-7 

IV-1.8 Character Display I/O IV-1-8 

IV-1.9 Standard I/O Connections IV-1-9 

IV-1.10 Summary IV-1-9 



Chapter 2. Using Basic I/O 



IV-2.1 Opening and Qosing an I/O Device IV-2-2 

IV-2.2 Reading and Writing Bytes IV-2-3 

IV-2.3 Handling End-of-File IV-2-3 

IV-2.4 Using Default I/O Connections IV-2-4 

IV-2.5 Positioning Within a Byte Stream IV-2-5 

IV-2.6 Reading and Inserting Records Sequentially IV-2-6 



Chapter 3. Managing Stream Files 



IV-3.1 Concepts IV-3-2 

IV-3.1.1 What Is a Stream File? IV-3-2 

IV-3.1.2 Using Access Methods with Stream Files IV-3-3 

IV-3.1.2.1 Byte Stream I/O IV-3-3 

IV-3.1.2.2 Record I/O IV-3-3 

IV-3.1.3 Temporary FQes IV-3-4 

IV-3.2 Techniques IV-3-5 

IV-3.2.1 Creating a Stream File IV-3-5 

IV-3.2.2 Copying a Stream File IV-3-6 

IV-3.2.3 Emptying a Stream File IV-3-6 

IV-3.2.4 Deleting a Stream File IV-3-6 

IV-3.2.5 Creating Temporary Files IV-3-7 

IV-3.3 Summary IV-3-8 



xiv Contents 



PRELIMINARY 



Chapter 4. Using Windows 



IV-4.1 Concepts IV-4-2 

IV-4.1.1 Terminals and Windows IV-4-3 

IV-4.1.2 Accessing Windows IV-4-4 

IV-4.1.3 Window Coordinates IV-4-4 

IV-4.1.4 Terminal Attributes IV-4-5 

IV-4.1.5 The InputModel IV-4-6 

IV-4.1.6 The Output Model IV-4-7 

IV-4.1.7 Overlapped Windows IV-4-7 

IV-4.1.8 Some Key Points IV-4-9 

IV-4.1.9 Resizing a Window IV-4-10 

IV-4.1. 10 Basic Window Operations IV-4-12 

IV-4.1. 11 Window Style IV-4-12 

IV-4.1. 12 Menus and Windows IV-4-13 

IV-4.1.12.1 Menu Hierarchy IV-4-13 

IV-4.1. 12.2 Building and Installing a Menu IV-4-14 

IV-4.1. 13 User Agents IV-4-15 

IV-4.1. 14 Character Terminal Manager IV-4-15 

IV-4.1. 15 Character Terminal Manager Support for Input Operations IV-4-15 

IV-4.1. 16 Character Terminal Manager Support for Output Operations IV-4-16 

IV-4. 1.17 Character Terminal Manager Support for Access Method Operations . . IV-4-16 
IV-4.1. 17.1 Character Terminal Manager Support for By te_Stream_AM ... IV-4-16 

IV-4. 1.17.2 Character Terminal Manager Support for Record_AM IV-4-17 

IV-4. 1.17.3 Character Terminal Manager Support for 

Char act er_Display_AM IV-4-18 

IV-4.2 Techniques IV-4-18 

IV-4.2.1 Obtaining an AD for the Underlying Terminal IV-4-18 

IV-4.2.2 Creating a Window IV-4-19 

IV-4.2.3 Setting a Window's Attributes IV-4-19 

IV-4.2.4 Setting a Window's Style IV-4-19 

IV-4.3 Summary IV-4-20 



Chapter 5. Using Character Display I/O 



IV-5.1 Concepts IV-5-2 

IV-5.1.1 Character Display Devices IV-5-2 

IV-5.1.2 The Frame Buffer IV-5-2 

IV-5.1.3 The OutputModel IV-5-4 

IV-5.1.4 The InputModel IV-5-4 

IV-5.1.5 Window Attributes IV-5-6 

IV-5.1.6 Operations IV-5-6 

IV-5.2 Techniques IV-5-8 

IV-5.2.1 Opening a Window IV-5-8 

IV-5.2.2 Clearing the Frame Buffer IV-5-9 

IV-5.2.3 Writing to the Frame Buffer IV-5-9 

IV-5.2.4 Moving the Cursor to an Absolute Position IV-5-9 



Contents xv 



rKliJLlJVUINAKY 



IV-5.2.5 Moving the Cursor Relative to its Current Position IV-5-10 

IV-5.2.6 Reading Input Events IV-5-10 

IV-5.2.7 Inserting Characters IV-5-11 

IV-5.2.8 Deleting Characters IV-5-11 

IV-5.2.9 Identifying the Underlying Device IV-5-11 

IV-5.3 Summary IV-5-11 



Chapters. Printing 



IV-6.1 Concepts IV-6-2 

IV-6.1.1 Spool Queue IV-6-3 

IV-6.1.2 PrintDevice IV-6-3 

IV-6.1.3 Spooled Printing IV-6-3 

IV-6.1.4 Direct Printing : IV-6-3 

IV-6.1.5 SpoolFile IV-6-3 

IV-6.1.6 Printer Lists IV-6-3 

IV-6.1.7 Print Area and Print Position IV-6-4 

IV-6.1.8 Requesting Form Type and Sheet Size IV-6-4 

IV-6.1.9 Printinfo ,...., IV-6-5 

IV-6.1. 10 Print Properties IV-6-5 

IV-6.1.1 1 Implementation of Spool Device Attributes IV-6-5 

IV-6.1. 12 Delayed Printing IV-6-7 

IV-6.1. 13 Banner Page and Print Termination Message IV-6-7 

IV-6.1. 14 Default Properties IV-6-7 

IV-6.2 Techniques IV-6-8 

IV-6.2.1 Printing to a Spool File IV-6-8 

IV-6.2.2 Printing Directly to a Printer IV-6-9 

IV-6.2.3 Controlling Print Properties IV-6-10 

IV-6.2.4 Administering Spool Devices IV-6-1 1 

IV-6.2.5 Adding a New Printer IV-6-12 

IV-6.3 Summary IV-6-12 



Chapter 7. Understanding Structured Files 



IV-7.1 Stream Files and Structured Files IV-7-2 

IV-7.1.1 Data Areas IV-7-3 

IV-7.2 Records IV-7-3 

IV-7.3 Buckets IV-7-4 

IV-7.4 Indexes IV-7-4 

IV-7.5 Stmcmred File Organizations IV-7-4 

IV-7.5.1 Sequential Files IV-7-5 

IV-7.5.2 Relative Files IV-7-5 

IV-7.5.3 Unordered Files IV-7-6 

IV-7.5.4 Clustered Files IV-7-7 

IV-7.5.5 HashedFiles IV-7-8 

IV-7.5.6 File Descriptors IV-7-8 

IV-7.6 Using Byte Stream and Record I/O withFiles IV-7-9 

IV-7.7 Structured FQes and Transactions IV-7-10 



xvi Contents 



PRELIMINARY 



IV-7.8 Summary IV-7-10 



Chapter 8. Managing Files and Indexes 

IV-8.1 Concepts IV-8-2 

IV-8.1.1 IndexKeys IV-8-2 

IV-8.1.2 Index Stmctures IV-8-3 

IV-8.1.2.1 B-Tree Alternate Index IV-8-3 

IV-8.1.2.2 B-Tree Organization Index IV-8-4 

IV-8.1.2.3 Hashed Organization Index IV-8-5 

IV-8.1.3 Choosing Indexes IV-8-5 

IV-8.1.4 Record DDefs IV-8-6 

IV-8.1.5 Index Key DDefs IV-8-7 

IV-8.1.6 NuU Values IV-8-9 

IV-8.2 Techniques IV-8-10 

IV-8.2.1 Defining Record DDefs IV-8-10 

IV-8.2.2 Defining Index Key DDefs IV-8-12 

IV-8.2.3 CreatingFiles IV-8-12 

IV-8.2.4 Building Organization Indexes IV-8-14 

IV-8.2.5 Building Alternate Indexes IV-8-15 

IV-8.3 Summary IV-8-16 



Chapter 9. Using Record I/O with Structured Files 

IV-9.1 Concepts IV-9-2 

IV-9.1.1 Current Record Pointer IV-9-2 

IV-9.1.2 Access Modes IV-9-3 

IV-9.1.2.1 Physical-Sequential Access IV-9-3 

IV-9.1.2.2 Physical-Random Access IV-9-4 

IV-9.1.2.3 Indexed-Sequential Access IV-9-5 

IV-9.1.2.4 Indexed-Random Access IV-9-7 

IV-9.1.3 Record I/O and Structured Files IV-9-8 

IV-9.1.3.1 Sequential Files IV-9-8 

IV-9.1.3.2 Relative Files IV-9-8 

IV-9.1.3.3 HashedFiles IV-9-9 

IV-9.1.4 End of File IV-9-9 

IV-9.1.4.1 End of File for Indexed Access IV-9-9 

IV-9.1.5 Record I/O and Transactions IV-9-11 

IV-9.1.6 Files and Disk Hushes IV-9-11 

IV-9.1.7 Record I/O Operation Status IV-9-11 

IV-9.2 Techniques IV-9-12 

IV-9.2.1 Opening and Qosing Structured Files IV-9-12 

IV-9.2.2 Setting OpenMode IV-9-13 

IV-9.2.3 Inserting Records IV-9-13 

IV-9.2.4 Accessing Fields in Record Buffers IV-9-14 

IV-9.2.5 Deleting Records IV-9-14 

IV-9.2.6 Reading and Updating Records IV-9-15 

IV-9.2.7 Using Physical-Random Access IV-9-17 



Contents xvii 



rKlil-,llVUl^ AK I 



IV-9.2.8 Using Physical-Sequential Access IV-9-18 

IV-9.2.9 Using Indexed-Random Access IV-9-19 

IV-9.2.10 Using Indexed-Sequential Access , IV-9-20 

IV-9.2.11 Reading Key Values Sequentially IV-9-22 

IV-9.2.12 Reading and Updating Records by Key IV-9-23 

IV-9.3 Summary IV-9-23 



Chapter 10. Locking Files and Records 

IV-lO.l Concepts IV-10-2 

IV- 10.1.1 Concurrency Control and Recovery IV-10-3 

IV-10.1.2 Transaction Locking IV-10-4 

IV-10.1.2.1 LockModes IV-10-5 

rV-10.1.2.2 Lock Mode Compatibility IV-10-6 

IV-10.1.3 Acquiring Locks IV-10-6 

IV-10.1.4 LockEscalation IV-10-7 

IV-10.1.5 Releasing Locks IV-10-7 

IV- 10.1.6 Consistency Levels IV-10-7 

IV- 10.1.7 Reading Key Range Values IV-10-8 

IV-10.1.8 Locking and Nested Subtransactions IV-10-8 

IV-10.1.9 Lock Contention IV-10-10 

IV-10.1.10 Logging IV-10-11 

IV-10.1.1 1 Transactions and Opened Device Objects IV-10-1 1 

IV- 10. 1.12 File-Level Locks Associated witii Opened Devices IV-10-12 

IV-10.1.13 File Administration Operations and Locking IV-10-12 

IV-10.2 Techniques IV-10-12 

IV- 10.2.1 Using Level 3 Consistency IV-10-12 

IV-10.3 Summary IV-10-14 



Ciiapter 11. Processing Collections of Records 

IV-ll.l Concepts IV-11-3 

IV-11.1.1 Reading Records IV-11-3 

IV-ll.l. 1.1 Record Streams IV-11-4 

IV-ll.l. 1.2 DDefs and Record Processing Support IV-11-5 

IV-11.1.2 Updating Records IV-11-5 

IV-11.1.3 Database Operations IV-11-5 

IV-11.1.4 Selection IV-11-6 

IV-11. 1.4.1 Customizing a Selection IV-11-7 

IV-1 1.1.4.2 Using tiie Associate_index_selection_ftmction Call IV-11-7 

IV- 11. 1.4.3 Using the Associate_read_procedure Call IV-11-7 

IV-11. 1.5 Projection IV-11-7 

IV-11. 1.5.1 Usingthe Associate_primary_data_pro jection Call ..IV-11-8 

IV-11. 1.5.2 Using the As sociate_index_j3roject ion Call IV-11-9 

IV-11. 1.6 Difference, Intersection, and Union IV-11-9 

IV- 11. 1.7 Interaction Between Record Processing Calls IV-11-9 

IV-11. 1.8 Joins IV-11-10 

IV-11.1.9 Sorting and Merging IV-11-11 



xviii Contents 



FKKLIMIINAKY 



IV-11. 1.9.1 Sorting Records IV-11-12 

IV-11. 1.9.2 Sort Ordering IV-11-13 

IV-11. 1.9.3 Stable Sorts IV-11-13 

IV-11.2 Techniques IV-11-13 

IV-11.2.1 Selecting a Set of Records IV-11-14 

IV-11.2.2 Using Projection on an Index IV-11-15 

IV-11.2.3 Joining Records from Two Devices IV-11-16 

IV-11.2.4 Sorting Records in a FUe IV-11-16 

IV- 11.2.5 Sorting and Merging Records from Two Files IV-11-17 

IV-11.3 Summary IV-11-18 



Contents xix 



FKIiLlMirSAKY 



Part V. Human Interface Services. 



Chapter 1. Understanding Human Interface Services 

V-l.l Concepts V-1-3 

V-1.1.1 Why Use Human Interface Services? V-1-4 

V-1.1.2 Utilities V-1-4 

V-1.1.3 Command Service V-1-6 

V-1. 1.3.1 Command Concepts V-1-7 

V-1. 1.3.2 Command Summary V-1-8 

V-1. 1.4 Environment Service V-1-8 

V-1. 1.4.1 Environment Variable Concepts V-1-9 

V-1. 1.4.2 Environment Variable Summary V-1-11 

V-1. 1.5 Menu Service V-1-11 

V-1. 1.5.1 Menu Concepts V-1-12 

V-1. 1.5.2 Menu Summary V-1-12 

V-1. 1.6 Form Service V-1-12 

V-1. 1.6.1 Form Summary V-1-14 

V-1. 1.7 Report Service V-1-15 

V-1. 1.7.1 Report Concepts V-1-15 

V-1. 1.7.2 Report Summary V-1-17 

V-1.2 Summary V-1-17 



Chapter 2. Creating a BiiN^"" Application Program 

V-2.1 Concepts V-2-4 

V-2.1.1 Designing a BiiN™ Program V-2-4 

V-2.1.2 Defining the Application's Data Structure V-2-5 

V-2.1.3 Example Program Overview V-2-5 

V-2.2 Techniques V-2-10 

V-2.2.1 Creating and Processing the Invocation Command V-2-10 

V-2.2.2 Using Windows in a Program V-2-11 

V-2.2.3 Processing a Menu Selection V-2-12 

V-2.2.4 Displaying a Message V-2-15 

V-2.2.5 Getting Data from a Form V-2-17 

V-2.2.6 Displaying Data Using a Form V-2-19 

V-2.2.7 Updating aFile V-2-20 

V-2.2.8 Printing a Report from aFile V-2-21 

V-2.2.9 Printing a Report from a Sorted File V-2-24 

V-2.3 Summary V-2-28 



Chapter 3. Building New Commands 

V-3.1 Concepts V-3-2 

V-3.1.1 Developing Command-Driven Programs V-3-4 



XX Contents 



PRELIMINARY 



V-3.1.2 Types of Commands V-3-4 

V-3.1.2.1 BuQt-in Commands V-3-5 

V-3.1.2.2 CLEX Commands V-3-6 

V-3.1.2.3 Program-Defined Commands V-3-6 

V-3.1.3 Review of Command Syntax V-3-7 

V-3.1.3.1 Command Name V-3-7 

V-3.1.3.2 Argument Types and Values V-3-8 

V-3.1.3.3 Control Options V-3-9 

V-3. 1.4 Review of Command Definitions V-3-10 

V-3.1.5 Types of Command Input V-3-11 

V-3.1.6 Alternatives to Command Input V-3-12 

V-3. 1.7 Entering Commands to Programs V-3-12 

V-3.2 Techniques V-3-13 

V-3.2.1 Defining an Invocation Command V-3-13 

V-3.2.2 Defining a Runtime Command Set V-3-14 

V-3.2.3 Reading the Invocation Command V-3-14 

V-3.2.4 Processing Command Arguments V-3-14 

V-3.2.5 Processing Runtime Commands V-3-16 

V-3.2.6 Reading a Command Input Line as Text V-3-16 

V-3.2.7 Executing Commands from a Program V-3-16 

V-3.3 Summary V-3-17 



Chapter 4. Programming with Command Language Variables 

V-4.1 Concepts V-4-3 

V-4.1.1 System Variables V-4-4 

V-4.2 Techniques V-4-5 

V-4.2.1 Read and Set an Environment Variable's Value V-4-5 

V-4.2.2 Display all Environment Variable Names V-4-6 

V-4.2.3 Get and Set Environment Variable Values in ASCII V-4-7 

V-4.2.4 Create and Remove an Environment Variable V-4-8 

V-4.3 Summary V-4-9 



Chapter 5. Programming with Menus 



V-5.1 Concepts V-5-3 

V-5.1.1 Why Use Menus? V-5-3 

V-5.2 Techniques V-5-3 

V-5.2.1 Define a Menu Group V-5-4 

V-5.2.2 Install a Menu Group in a Window V-5-5 

V-5.2.3 Enable an Installed Menu Group V-5-6 

V-5.2.4 Get a Menu Selection V-5-6 

V-5.2.5 Display a Checkmark for a Menu Item V-5-7 

V-5.2.6 Change a Window's Enabled Menu Group V-5-7 

V-5.2.7 Remove an Installed Menu Group fi"om a Window V-5-7 

V-5.3 Summary V-5-8 



Contents xxi 



rKKLUVUINAKl 



Chapter 6. Understanding Forms 



V-6.1 Creating a Form Description V-6-4 

V-6.2 Record I/O V-6-4 

V-6.3 Form Elements V-6-4 

V-6.4 Texts V-6-5 

V-6.5 ScreenFields V-6-5 

V-6.5.1 Character Fields V-6-5 

V-6.5.2 OptionFields V-6-7 

V-6.6 Enumeration V-6-7 

V-6.6.1 Null Enumeration Element V-6-9 

V-6.7 Protecting Fields V-6-9 

V-6.8 DataFields V-6-9 

V-6.9 Subfoms V-6-9 

V-6.10 Groups V-6-9 

V-6.11 Piles V-6-10 

V-6.12 Expansion and Contraction of Forms V-6-12 

V-6.13 Subroutines and the Subroutine Interface V-6-13 

V-6.14 Processing Routines V-6-14 

V-6.15 Key Catchers V-6-15 

V-6.16 Symbolic Keys V-6-16 

V-6.17 Key Lists V-6-19 

V-6.18 Form Name Environments V-6-19 

V-6.19 Execution Paths V-6-20 

V-6. 19. 1 Explicit Modification of the Path Registers V-6-21 

V-6.19.2 Implicit Modification of the Path Registers V-6-21 

V-6.20 Messages and Help Information V-6-21 

V-6.21 Window Management V-6-22 

V-6.22 Summary V-6-22 



Chapter 7. Programming with Forms 



V-7.1 Creating Executable Forms V-7-2 

V-7.2 Command Language Variables V-7-3 

V-7.3 Form Utilities '. V-7-5 

V-7.4 Editing Translation Tables V-7-6 

V-7.5 Techniques V-7-6 

V-7.5.1 Opening and Qosing Forms V-7-6 

V-7.5.2 Executing Forms V-7-7 

V-7.5.3 Setting and Resetting the Initial State of a Form V-7-8 

V-7.5.4 Inserting, Storing, and Deleting the Contents of Screen and Data Fields . . V-7-8 

V-7.5.5 Controlling the Execution Path V-7-9 

V-7.5.6 Processing Routines and Key Catchers V-7-10 

V-7.5.7 Defining a Processing Routine V-7-10 

V-7.5.8 Defining a Key Catcher V-7-11 

V-7.5.9 Interrupting Execution V-7-1 1 

V-7.5.10 Adding and Removing Group Instances V-7-11 



xxii Contents 



FKELIMIINAKY 



V-7.5.1 1 Modifying the Appearance of a Fonn V-7-12 

V-7.5.12 Inquiring About an Element, Form Sheet, and Form Status V-7-13 

V-7.5.13 Inquiring About the Last Edited Sheet Element and Input Event V-7-14 

V-7.6 Summary V-7-14 



Chapter 8. Generating Reports 



V-8.1 Concepts V-8-2 

V-8.1.1 Report Characteristics V-8-2 

V-8.1.2 Control Groups V-8-5 

V-8.1.3 Representation of Report Descriptions V-8-6 

V-8, 1.4 Creating and Modifying a Report Description V-8-7 

V-8.1.5 Report CL Variables V-8-9 

V-8. 1.6 Printing a Report From the Conmiand Line V-8-11 

V-8.2 Techniques V-8-11 

V-8.2.1 Printing a Report From Your Program V-8-1 1 

V-8.2.2 Setting Global Assignments V-8-13 

V-8.3 Summary V-8-14 



Contents xxiii 



rKELlMlINAKY 



Part VL Program Services. 



Chapter 1. Understanding Program Execution 

VI-l.l Definition of a Program VI-1-2 

VI-1.2 Program Structure VI-1-2 

VI-1.2.1 The Program Object VI-1-3 

VI-1.2.2 The Domain Object VI-1-4 

VI-1.2.3 The Static Data Object VI-1-5 

VI-1.2.4 The Instruction Object VI-1-6 

VI-1.2.5 The Stack Object VI-1-6 

VI-1.2.6 The Public Data Object VI-1-6 

VI-1.2.7 The Debug Object VI-1-7 

VI-1.2.8 The Handler Object VI-1-8 

VI-1.3 Invoking a Program VI-1-8 

VI-1.4 Program Execution VI-1-9 

VI-1.4.1 Sessions, Jobs, and Processes VI-1-9 

VI-1.4.2 Process Globals VI-1-10 

VI-1.5 Interprocess Communication VI-1-12 

VI-1.5.1 Events VI-1-12 

VI-1.5.2 Pipes VI-1-14 

VI-1.5.3 Pipes vs. Events VI-1-15 

VI-1.6 Process Control VI-1-15 

VI-1.6.1 Process States VI-1-15 

VI-1.6.2 Local Event Cluster VI-1-16 

VI-1.7 Semaphores VI-1-17 

VI-1.8 Use of Multiple Processes VI-1-19 

VI-1.9 Summary VI-1-21 



Chapter 2. Building Concurrent Programs 

VI-2.1 Getting a Process Globals Entry VI-2-4 

VI-2.2 Setting a Process Globals Entry VI-2-4 

VI-2.3 Creating a Process VI-2-5 

VI-2.4 Getting Process Information VI-2-7 

VI-2.5 Suspending and Resuming a Process VI-2-7 

VI-2.6 Terminating a Process VI-2-8 

VI-2.7 Signaling an Event VI-2-9 

VI-2.8 Establishing an Event Handler VI-2-10 

VI-2.9 Waiting for Events VI-2-11 

VI-2.10 Connecting Processes with a Pipe VI-2-12 

VI-2.11 Locking Shared Data Structures VI-2-13 



xxiv Contents 



PRELIMINARY 



Chapters. Scheduling 



VI-3.1 What the Scheduler Is VI-3-2 

VI-3.2 The Scheduler's Objectives VI-3-2 

VI-3.3 The Scheduler's Task VI-3-2 

VI-3.4 CPU Scheduling VI-3-3 

VI-3.4.1 CPU Scheduling Model VI-3-3 

VI-3.4.1.1 High Level Scheduling VI-3-3 

VI-3.4.1.2 Low Level ScheduHng VI-3-4 

VI-3.4.1.3 Processor Preemption VI-3-4 

VI-3.4.1.4 Qasses and Priorities VI-3-4 

VI-3.4.1.5 Processor Claim and Job Time Limit VI-3-5 

VI-3.4.1.6 Medium Level Scheduling VI-3-5 

VI-3.4.2 Scheduling Service Objects (SSOs) VI-3-6 

VI-3.4.2.1 Service Classes VI-3-6 

VI-3.4.2.2 SSO Priority VI-3-6 

VI-3.4.2.3 Time Slice VI-3-7 

VI-3.4.2.4 Memory Type VI-3-7 

VI-3.4.2.5 Initial Age VI-3-7 

VI-3.4.2.6 Age Factor VI-3-7 

VI-3.4.3 Resource-Driven Priorities VI-3-7 

VI-3.4.3.1 Priorities Used VI-3-8 

VI-3.4.3.2 AnExample VI-3-8 

VI-3.5 Memory Scheduling VI-3-9 

VI-3.6 I/O Scheduling VI-3-9 

VI-3.7 Summary VI-3-9 



Contents xxv 



PRELIMINARY 



Part VIL Type Manager Services. 



Chapter 1. Understanding Objects 



VIM.l Why Use Objects? VIM-2 

VII-1.1.1 Data Abstraction VIM-2 

VIM. 1.2 Memory Protection Vn-1-3 

VII-1.1.3 Secure and Dynamic Memory Management VIM -4 

VIM. 1.4 Support for Complex and Extensible Applications VIM -4 

VIM. 1.5 Uniform Storage Model for Peraianent and Volatile Memory VIM -4 

VIM. 1.6 Distributed Storage Model Vn-1-5 

Vn-1.2 How Objects Work VIM -5 

VIM.2.1 Object Sizes Vn-1-5 

VIM.2.2 Types VIM-5 

VIM.2.3 Object Protection Vn-1-6 

VIM.2.4 Attributes Vn-1-6 

VIM.2.5 The Inside View of an Object VIM-8 

VIM.3 Address Space Protection VII-1-10 

VIM.3.1 Access Descriptors VIM-12 

VIM.3.2 Type Managers .VIM-13 

VIM.3.3 Domains VIM-14 

Vn-1.4 Passive Objects VII-1-15 

VIM.4.1 Active Memory Vn-1-16 

VIM.4.2 Passive Store VII-1-16 

VIM.4.3 Passive ADs VII-M7 

VIM.4.4 Passive Store Protection - Authority Lists VII-1-18 

VIM.4.5 IDs VII-1-19 

VIM.4.6 Updating Stored Objects VIM-20 

VIM.5 Summary VII-1-20 



Chapter 2. Understanding Memory Management 

VII-2.1 Physical Memory Organization VII-2-2 

VII-2.2 Virmal Memory Organization VII-2-5 

VII-2.2.1 The ObjectTable VII-2-5 

VII-2.2.2 Object-Based Address Translation VII-2-7 

VII-2.2.3 Storage Resource Object VII-2-7 

VII-2.2.4 Object Representations VII-2-8 

VII-2.2.5 Frozen and Normal Memory Types VII-2-9 

VII-2.3 Different Allocation Policies Vn-2-9 

VII-2.4 Object Lifetimes VII-2-9 

VII-2.5 Object Deallocation Strategies VII-2-10 

VII -2.6 Controlling and Accounting for Memory Resources Vn-2-12 

VII-2.7 User-Transparent Memory Management Functions VII-2-12 

VII-2.7.1 Object Activation VII-2-12 

VII-2.7.2 Virtual Memory Paging VII-2-12 

VII-2.7.3 Global Garbage Collection Vn-2-13 



xxvi Contents 



PRELIMINARY 



VII-2.7.4 Compaction VII-2-13 

VII-2.7.5 Optimized Handling of Instruction Objects VII-2-13 

VII-2.8 Summary VII-2-13 



Chapter 3. Building a Type Manager 



VII-3.1 Concepts VII-3-2 

VII-3.1.1 The Type Manager Defines All Calls for a Type of Object VII-3-2 

VII-3.1.2 Type Managers Hide Data Representation Vn-3-3 

VII-3.1. 3 Only the Type Manager Has the Key to Access the Type's Objects VII-3-3 

VII-3.1.4 One Module Can Manage Multiple Types VII-3-3 

VII-3.2 Techniques VII-3-3 

VII-3.2.1 Defining the Public Type Vn-3-4 

VII-3.2.2 Defining Type Rights VII-3-5 

VII-3.2.3 Defining Exceptions VII-3-6 

VII-3.2.4 Defining the Type's Calls VII-3-6 

VII-3.2.5 Defining the Private Types VII-3-7 

VII-3.2.6 Defining Needed BiiN™ Ada Type Overlays VII-3-7 

VII-3.2.7 Creating the TDO VII-3-8 

VII-3.2.8 Binding to a Stored TDO VII-3-8 

VII-3.2.9 Implementing the Is_account Call VII-3-8 

VII-3,2.10 Implementing the Great e_account Call VII-3-9 

VII-3.2.11 Implementing the Create_stored_account Call VII-3-9 

VII-3.2. 12 Implementing Calls that Require Type Rights VII-3-10 

VII-3.2. 13 Implementing Calls that Do not Require Type Rights VII-3-1 1 

VII-3.2.14 Implementing the Destroy Call VII-3-11 

VII-3.2.15 Making Operations Atomic VII-3-12 

VII-3.2.16 Initializing the Type Manager VII-3-13 

VII-3.2. 17 Protecting the Type Manager from Otiier Services VII-3-14 

VII-3.3 Summary VII-3-15 



Chapter 4. Using Attributes 



VII-4.1 Concepts VII-4-3 

VII-4.2 Techniques VII-4-5 

VII-4.2.1 Defining a New Attribute VII-4-5 

VII-4.2.2 Defining an Attribute Instance VII-4-6 

VII-4.2.3 Initializing the Type's TDO VII-4-7 

VII-4.2.4 Initializing an Objects Attribute List VII-4-8 

VII-4.3 Summary VII-4-8 



Chapter 5. Managing Active Memory 



VII-5.1 A Brief Overview of How Memory Is Allocated VII-5-2 

VII-5.2 Collecting Garbage Objects - GCOL VII-5-3 

VII-5.2.1 Local GCOL VII-5-3 



Contents xxvii 



PRELIMIINARY 



VII-5.2.2 Global GCOL Vn-5-4 

VII-5.3 Techniques VII-5-5 

VII-5.3.1 Trimming the CaUer's Stack Vn-5-5 

VII-5.3.2 Starting Local Garbage Collection Vn-5-5 

VII-5.3.3 Setting/Changing Local GCOL Parameters VII-5-5 

VII-5.3.4 Stopping Local Garbage Collection Vn-5-6 

VII-5.3.5 Getting Information About a Job's Local Memory vn-5-6 

VII-5.4 Summary VII-5-6 



Chapter 6. Building Type Managers for Stored Objects 

VII.6.1 Concepts Vn-6-2 

VII-6.1.1 Storing and Retrieving Objects in Passive Store VII-6-2 

Vn-6.1.1.1 Lifetime Requirements VII-6-3 

VII-6.1.1.2 Storing Objects Requires Three Steps VII-6-3 

Vn-6.1.1.3 Object Trees in Passive Store VII-6-3 

VII-6.1.2 The Type Manager Can Customize Passive Store Operations VII-6-3 

Vn-6.1.3 Synchronizing Access to Objects - Transactions and Semaphores VII-6-4 

VII-6.2 Techniques VII-6-4 

VII-6.2.1 Defining the Type's CaUs VII-6-5 

Vn-6.2.2 Implementing the Great e_ac count call VII-6-6 

VII-6.2.3 Implementing the Create_stored_account Call VII-6-7 

VII-6.2.3.1 Starting, Commiting, and Aborting a Transaction VII-6-8 

Vn-6.2.3.2 Storing the Master AD VII-6-9 

VlI-6.2.3.3 Updating the Object VII-6-9 

VII-6.2.4 Implementing the Change_balance Call VII-6-9 

VII-6.2.5 Implementing the Transfer Call . . . Vn-6-11 

VII-6.2.6 Implementing the Destroy_account Call Vn-6-12 

VII-6.2.7 Initializing the Type Manager VII-6-13 

VII-6.2.8 Protecting the Type Manager VII-6-16 

VII-6.3 Summary VII-6-18 



Cliapter 7. Understanding System Configuration 

VII-7.1 Creating a Node's Configuration VII-7-3 

VII-7.2 Defining a Node's Configuration VII-7-4 

VII-7.3 Configuration Attribute Calls VII-7-4 

VII-7.4 Creating Configurable Objects VII-7-5 

VII-7.5 Attaching Objects to Configurable Objects VII-7-6 

VII-7.6 Configuring Software Services VII-7-6 

VII-7.7 Starting Configurable Objects VII-7-7 

VII-7.8 System SCOs and User SCOs VII-7-8 

VII-7.9 The configure Utility VII-7-9 

VII-7.10 Summary VII-7-9 



xxviii Contents 



PRELIMINARY 



Part VIII. Distribution Services. 



Chapter 1. Understanding Distribution 

VIII-l.l Introduction Vin-1-2 

VIII-1.2 What a Distributed System Can Do VIII-1-4 

VIII-1.3 Naming Vin-1-5 

VIII-1.3.1 The Qearinghouse Vin-1-6 

VIII-1.4 Conmiunications VIIM-8 

VIII-1.5 Review of the Computational Model VIII-1-10 

VIII-1.5.1 Processes, Jobs and Sessions VIII-1-10 

VIIM.5.2 Active andPassive ADs VIII-1-10 

VIII-1.5.3 Single and Multiple Activation Model VIII-1-1 1 

VIII-1.6 Single Activation Distributed Services Vni-1-13 

VIII-1.7 Protection in a Distributed System VIII-1-13 

VIII-1.8 Transparently Distributed Services VIII-1-14 

VIII-1.8.1 Passive Store VIII-1-14 

VIIM.8.2 Directories Vin-1-14 

VIII-1.8.3 IDs Vni-1-15 

Vni-1.8.4 Files VIII-1-16 

VIII-1.8.5 Data Integrity, Synchronization, and Transactions VIII-1-16 

VIII-1.9 Summary VIII-1-16 



Chapter 2. Building a Distributed Type l\/lanager 

Vni-2.1 Concepts VIII-2-2 

VIII-2.1.1 Homomorphs and Active Versions VIII-2-3 

VIII-2.1.2 TheRemoteCall VIII-2-3 

VIII-2.1.3 Synchronizing Access VIII-2-4 

VIII-2.2 Techniques VIII-2-4 

VIII-2.2.1 Defining The Representation of The Object VIII-2-5 

VIII-2.2.2 Defining the Homomorph Template VIII-2-6 

VIII-2.2.3 Setting the Passive Store Attribute VIII-2-6 

VIII-2.2.4 Defining Buffers for Remote Procedure Calls VIII-2-7 

VIII-2.2.5 The Is_CaU VIII-2-7 

VIII-2.2.6 The The Create_ Calls VIII-2-8 

VIII-2.2.7 Implementing Calls that Require Remote Calls VIII-2-9 

VIII-2.2.7.1 Recognizing tiie Home Job VIII-2-10 

VIII-2.2.7.2 Making the Remote Procedure Call VIII-2-10 

VIII-2.2.7.3 The Server Stub Vin-2-11 

VIII-2.2. 8 Synchronizing with Transactions and Semaphores VIII-2-12 

VIII-2.2.9 Initialization VIII-2-12 

VIII-2.2.9.1 Private ADs are Hidden in the Static Data Object VIII-2-13 

VIII-2.2.9.2 Creating tiie Server VIII-2-13 

VIII-2.2.9.3 Creating and Registering tiie Service VIII-2-14 

VIII-2.2.9.4 Setting Up tiie Home Job VIII-2-14 

VIII-2.3 Summary VIII-2-15 



Contents xxix 



PRELIMINARY 



Part IX. Device Services. 



Chapter 1. Understanding Device IVIanagers and Device 
Drivers 

IX-l.l Concepts IX-1-3 

IX-1.2 I/O Model IX-1-3 

IX-1.2.1 AccessMethods IX-1-4 

IX-1.2.2 Device Managers IX-1-4 

IX-1.2.3 Device Drivers IX-1-4 

IX-1.2.4 Device Classes IX-1-4 

IX-1.2.5 I/O Mechanisms IX-1-4 

IX-1.2.6 The I/O Messages Mechanism IX-1-5 

IX-1.3 Data Transfer Via the I/O Messages Mechanism IX-1-6 

IX-1.3.1 I/O Recovery Agent IX-1-8 

IX-1.4 Data Transfer Via the Shared Queues Mechanism IX-1-8 

IX-1.5 Ousters and Ouster Servers IX-1-9 

IX-1.5.1 Administrative Interface IX-1-9 

IX-1.5.2 Device Driver Example IX-1-9 

IX-1.5.3 I/O Shared Queues Data Transfer Mechanism IX-1-10 

IX-1.6 Summary IX-1-13 



XXX Contents 



rKKUMlMAKY 



PartX. Appendixes. 



Appendix A. Ada Examples 



X-A.l Introduction" X-A-4 

X-A.2 Support Services X-A-4 

X-A.2.1 Example_Messages Package Specification X-A-5 

X-A.2.2 Long_lnteger_Ex Package Specification X-A-7 

X-A.2.3 Long_Integer_Ex Package Body X-A-8 

X-A.2.4 Make_menu_group_DDef _ex Procedure X-A-12 

X-A.2.5 Manage_application_environment_ex Procedure X-A-20 

X-A.2.6 String_list_ex Procedure X-A-23 

X-A.3 Directory Services X-A-23 

X-A.3.1 Create_directory_cmd_ex Procedure X-A-24 

X-A.3.2 Create_name_space_cmd_ex Procedure X-A-26 

X-A.3.3 List_current_directory_cmd_ex Procedure X-A-31 

X-A.3.4 Make_ob ject_public_ex Procedure X-A-33 

X-A.3.5 Show_current_directory_cmd_ex Procedure X-A-35 

X-A.4 I/O Services X-A-36 

X-A.4.1 DBMS_Support_Ex Package Specification X-A-37 

X-A.4.2 DBMS_Support_Ex Package Body X-A-38 

X-A.4.3 Employee_Filing_Ex Package Specification X-A-42 

X-A.4.4 Employee_Filing_Ex Package Body X-A-46 

X-A.4.5 Hello_ada_ex Procedure X-A-54 

X-A.4.6 Hello_OS_ex Procedure X-A-55 

X-A.4.7 Join_File_Ex Package Specification X-A-56 

X-A.4.8 Join_File_Ex Package Body X-A-57 

X-A.4.9 Record_Locking_Ex Package Specification X-A-61 

X-A.4. 10 Record_Locking_Ex Package Body X-A-62 

X-A.4.11 Output_bytes_ex Procedure X-A-64 

X-A.4.12 Output_records_ex Procedure X-A-65 

X-A.4.13 Print_cmd_ex Procedure X-A-67 

X-A.4.14 Print_Cind_Mes sages Package X-A-70 

X-A.4. 15 Record_AM_Ex Package Specification X-A-71 

X-A.4.16 Record_AM_Ex Package Body X-A-75 

X-A.4. 17 Simple_editor_cmd_ex Procedure X-A-84 

X-A.4.18 Simple_Editor_Ex Package Specification X-A-85 

X-A.4. 19 Simple_Editor_Ex Package Body X-A-89 

X-A.4.20 Stream_f ile_ex Procedure X-A-103 

X-A.5 Human Interface Services X-A-104 

X-A.5.1 Inventory_main Procedure X-A-105 

X-A.5.2 Inventory_Files Package Specification X-A-108 

X-A.5.3 Inventory_Files Package Body X-A-1 15 

X-A.5.4 Inventory_Forms Package Specification X-A-121 

X-A.5.5 Inventory_Forms Package Body X-A-126 

X-A.5.6 Invent or y_Menus Package Specification X-A-137 

X-A.5.7 Inventory_Menus Package Body X-A-140 

X-A.5.8 Invent or y_Reports Package Specification X-A-144 

X-A.5.9 Invent ory_Reports Package Body X-A-146 



Contents xxxi 



PRELIMINARY 



X-A.5.10 Inventory_Windows Package Specification X-A-152 

X-A.5.11 Inventory_Windows Package Body X-A-154 

X-A.5.12 Inventory_Messages Package Specification X-A-156 

X-A.6 Program Services X-A-156 

X-A.6.1 At_cmd_ex Procedure X-A-157 

X-A.6.2 At_Support_Ex Package Specification X-A-160 

X-A.6.3 At_Support_Ex Package Body X-A-162 

X-A.6.4 Compiler_Ex Package Specification X-A-168 

X-A.6.5 Compiler_Ex Package Body X-A-169 

X-A.6.6 Conversion_Support_Ex Package Specification X-A-172 

X-A.6.7 Memory_ex Procedure X-A-176 

X-A.6.8 Process_Globals_Support_Ex Package Specification X-A-177 

X-A.6.9 Process_Globals_Support_Ex Package Body X-A-182 

X-A.6.10 Synibol_Table_Ex Package Specification X-A-191 

X-A.6.1 1 Syinbol_Table_Ex Package Body X-A-193 

X-A.6.12 Word_Processor_Ex Package Specification X-A-197 

X-A.6.13 Word_Processor_Ex Package Body X-A-198 

X-A.6.14 View_device_main Procedure X-A-203 

X-A.6.15 VD_Def s Package Specification X-A-206 

X-A.6. 16 VD_Commands Package Specification X-A-208 

X-A.6.17 VD_Coinmands Package Body X-A-209 

X-A.6.18 VD_Devices Package Specification X-A-213 

X-A.6.19 VD_Devices Package Body X-A-215 

X-A.7 Type Manager Services X-A-218 

X-A.7.1 Acct_main_ex Procedure X-A-219 

X-A.7.2 Acct_Visual Package Specification X-A-236 

X-A.7.3 Acct_Visual Package Body X-A-238 

X-A.7.4 Account Manager Command File X-A-244 

X-A.7.5 Account_Types_Ex Package Specification X-A-250 

X-A.7.6 Account_Mgt_Ex Package Specification X-A-251 

X-A.7.7 Account_Mgt_Ex (Active Only) Package Body X-A-256 

X-A.7.8 Account_Mgt_Ex (Stored, Non-transaction-oriented) Package Body . X-A-261 

X-A.7.9 Account_Mgt_Ex (Stored, Transaction-oriented) Package Body X-A-267 

X-A.7.10 Stored_Account_TDO_Init_Ex Procedure X-A-276 

X-A.7. 11 Account_Type_Name_Ex Package Specification X-A-279 

X-A.7. 12 Account_Type_Name_Ex Package Body X-A-280 

X-A.7.13 Type_Name_Attr_Ex Package Specification X-A-281 

X-A.7. 14 Type_Naine__Attr_Ex Package Body X-A-282 

X-A.7.15 Type_Name_Attribute_Init_Ex Procedure X-A-283 

X-A.7. 1 6 Re f u se_Re s et_Act i ve_Ve r s io n_Ex Package Specification . . . X-A-284 

X-A.7.17 Refuse_Reset_Active_Version_Ex Package Body X-A-285 

X-A.7. 18 Account_Mgt_Ex (Distributed) Package Body X-A-286 

X-A.7.19 Distr_Acct_Call_Stub_Ex Package Specification X-A-298 

X-A.7.20 Distr_Acct_Call_Stub_Ex Package Body X-A-300 

X-A.7.21 Distr_Acct_Server_Stub_Ex Package Specification X-A-304 

X-A.7.22 Distr_Acct_Server_Stub_Ex Package Body X-A-306 

X-A.7.23 Distr_Acct_Init Procedure X-A-308 

X-A.7.24 Distr_Acct_Home_Job_Ex Procedure X-A-312 

X-A.7.25 Makefile X-A-313 

X-A.7.26 Named_copy_ex Procedure X-A-315 

X-A.7.27 Older than ex Function X-A-317 



xxxii Contents 



PRELIMINARY 



Appendix B. Glossary 



Contents xxxiii 



PRELIMINARY 



List of Figures 



I-l-l. Networked, Distributed, Multiprocessing Nodes 1-1-3 

1-1-2. How the Dispatcher Handles Multiprocessing 1-1-4 

1-1-3. How the BiiN™ OS Aids Fault Tolerance 1-1-6 

1-1-4. The OS Interface is Made up of Services, Packages, and Calls 1-1-12 

1-1-5. ADs Provide Access and Protection to Services 1-1-14 

1-1-6. An AD Showing Type Rights 1-1-16 

II-l-l. Data Structures for String List, Text, and Long Integer 11-1-2 

II-2-1. AD and Object n-2-2 

II-2-2. A Valid Access Descriptor 11-2-3 

II-3-1. Passive Store is a Distributed Object Filing Service that Unifies all Nodes in a 

BiiN™ System II-3-2 

II-3-2. A Single Object can have Passive and Active Versions 11-3-4 

II-3-3. A Stored Object II-3-10 

II-3-4. Life History of a Stored Object Part I II-3-11 

II-3-5. Life History of a Stored ObjectPart II II-3-12 

II-3-6. A Single Object can have Multiple Active Versions II-3-13 

II-3-7. Copying an Object Tree II-3-21 

II-5-1. Incidents Associate Errors with Messages II-5-3 

III-l-l. Directories Contain <Name, AD> Pairs ni-1-2 

III-1-2. A Directory Structure with Aliases in-1-3 

III-1-3. A Directory is Protected with an Authority List III-1-5 

III-1-4. Directory_Mgt uses the Qearinghouse to Resolve Network Names III-1-6 

III-2-1. Directories Contain <Name, AD> Pairs III-2-2 

ni-3-1. A Caller Accesses a Protected Object III-3-2 

III-3-2. Partsof anID III-3-4 

III-3-3. AProcess's ID List in-3-5 

ni-3-4. Multiple Objects Sharing an Authority List III-3-6 

III-3-5. Evaluating Access During a Retrieve III-3-7 

III-3-6. Example: Evaluating Access During a Retrieve III-3-8 

III-4-1. A Name Space Lists Directories to be Searched III-4-2 

III-5-1. A Symbolic Link III-5-2 

IV-1-1. Opened Devices are I/O Channels to Devices IV-1-3 

IV-1-2. ConcurrentVO IV-1-4 

IV-1-3. Access Methods are Supported by Multiple Devices IV-1-5 

IV-1-4. Byte Stream I/O IV-1-7 

IV-1-5. Record I/O IV-1-7 

IV-1-6. Character Display I/O IV-1-8 

IV-3-1. Stream File Being Opened for Access IV-3-2 

IV-3-2. Line Formats for Stream Files IV-3-4 

IV-4-1. Windows Displayed on a Physical Terminal IV-4-3 

IV-4-2. Window_Services Coordinate Systems IV-4-5 

IV-4-3. Relationship Between Window and View IV-4-8 

IV-4-4. Example of Overlapped Windows IV-4-9 

IV-4-5. Example Showing Two Possible Resize Rules IV-4-10 

IV-4-6. Left Top Resize Rule IV-4-11 

IV-4-7. Contents Resize Rule Example IV-4-12 

IV-4-8. Menu Bar and Pull-down Menu IV-4-14 



xxxiv Contents 



PRELIMINARY 



IV-5-1. Views, Windows, and Frame Buffers IV-5-3 

IV-5-2. The Frame Buffer Coordinate System IV-5-4 

IV-6-1. Spooled Printing IV-6-2 

IV-6-2. Print Area IV-6-4 

IV-7-1. File Objects and Data Areas IV-7-3 

IV-7-2. Sequential File IV-7-5 

IV-7-3. Relative File IV-7-6 

IV-7-4. UnorderedFile IV-7-6 

IV-7-5. ClusteredFUe IV-7-7 

IV-7-6. HashedFile IV-7-8 

IV-8-1. An Indexed File IV-8-2 

IV-8-2. Index Key Values that Point to Records IV-8-3 

IV-8-3. B-Tree Alternate Index IV-8-4 

IV-8-4. Clustering B-Tree Organization Index IV-8-4 

IV-8-5. Hashed Organization Index IV-8-5 

IV-8-6. A Simple Record DDef IV-8-6 

IV-8-7. A Simple Derived Index Key DDef IV-8-8 

IV-8-8. Layout of a Derived Index Key DDef IV-8-9 

IV-9-1. A Record I/O Read Operation IV-9-2 

IV-9-2. Physical-Sequential Access IV-9-4 

IV-9-3. Physical-Random Access IV-9-5 

IV-9-4. Indexed-Sequential Access IV-9-6 

IV-9-5. Indexed-Random Access IV-9-7 

IV-9-6. EOF Detection During Indexed-Sequential Access IV-9-10 

IV-10-1. Lost Update Problem IV-10-2 

IV-10-2. Locking Hierarchy IV-10-4 

IV- 10-3. An Update with an X-lock IV-10-5 

IV-10-4. Locks Inherited by Subtransactions IV-10-10 

IV-11-1. Customizing a Read Call IV-11-2 

rV-11-2. Associating a Record ID Stream with aFile IV-11-4 

IV-11-3. DBMS Operations IV-11-6 

IV-11-4. A Primary Data Projection IV-11-8 

IV-11-5. A Join Operation IV-11-10 

IV-11-6. Sorting and Merging Records IV-11-12 

TM 

V-1-1. Human Interface Services and a BiiN Program V-1-2 

V-1-2. Utility, Data Definition, and Service V-1-5 

V-1-3. BiiN™ Application Program and the Command Service V-1-6 

V-1-4. Command Language Variables V-1-9 

V-1-5. BiiN™ Application Program and Menus V-1-1 1 

V-1-6. Example Form V-1-13 

V-1-7. Annotated Executable Form V-1-14 

V-1-8. Example Report V-1-15 

V-1-9. Layout of a Standard Report Page V-1-16 

V-2-1. Typical BiiN™ Application Program V-2-3 

V-2-2. File Data Definition and Associated Forms and Reports V-2-5 

V-2-3. Example Program Menus V-2-6 

V-2-4. Example Program Source Files V-2-9 

V-2-5. File and an Associated Report V-2-22 

V-4-1. Command Language Variables V-4-2 

V-5-1. BiiN™ Application Program and Menus V-5-2 

V-6-1. Sample Paper Form V-6-2 

V-6-2. Annotated Executable Form V-6-3 



Contents xxxv 



FKELIMIMAKY 



V-6-3. Character Field V-6-5 

V-6-4. OptionField V-6-7 

V-6-5. Overlaid Enumeration: Initial Value V-6-8 

V-6-6. Overlaid Enumeration: Subsequent Value V-6-8 

V-6-7. Scattered Enumeration V-6-8 

V-6-8. Group Instances V-6-10 

V-6-9. Group Instances in a Horizontal Deployment V-6-10 

V-6-10. Group Instances with Multiple Sheet Elements V-6-10 

V-6-11. Form withaPile V-6-11 

V-6-12. FirstPile Usage V-6-11 

V-6-13. Second Pile Usage V-6-12 

V-6-14. ThirdPile Usage V-6-12 

V-6-15. Effect of the Expansion of a Group Instance: Before Expansion V-6-13 

V-6-16. Effect of the Expansion of a Group Instance: After Expansion V-6-13 

V-8-1. Sample Report V-8-2 

V-8-2. Page Series of a Report V-8-3 

V-8-3. Parts of a Report Page V-8-4 

V-8-4. Report With Nested Control Groups V-8-5 

V-8-5. Report With Control Breaks V-8-6 

V-8-6. Report Parts of a Report Description V-8-7 

V-8-7. Layout of a Standard Report Page V-8-8 

VI-1-1, Static Structure of a Program VI-1-3 

VI-1-2. Program Object VI-1-4 

VI-1-3. Domain Object VI-1-5 

VI-1-4. Static Data, Instruction, and Stack Objects VI-1-6 

VI-1-5. Public Data Object VI-1-7 

VI-1-6. Debug Object VM-8 

VI-1-7. Job and Processes VI-1-10 

VI-1-8. Events can be Handled, Queued, or Discarded VI-1-14 

VI-1-9. Pipe I/O VI-1-14 

VI-1-10. Major Process States VI-1-16 

VI-1-11. Binary Semaphores VI-1-18 

VI- 1-12. Processes Connected by a Pipe Speed Up a Compiler VI- 1-19 

VI-1-13. Multiple Processes Speed Up a Large Array Calculation VI-1-20 

VI-1-14. A Separate Spelling Checker Process Preserves Word Processor 

Responsiveness VI-1-20 

VI-2-1. Job and Processes VI-2-2 

VI-3-1. High-level Scheduling VI-3-3 

VI-3-2. Low-level Scheduling VI-3-4 

VII-1-1. An Object as a Black Box VII-1-3 

VII-1-2. An Object Can be Resized VII-1-5 

VII-1-3. Object and Access Descriptor VII-1-6 

VII-1-4. How Attributes Work VII-1-7 

VII-1-5. Objects Are Typed and Protected VII-1-9 

VII-1-6. Threefold object protection VII-1-11 

VII-1-7. An Access Descriptor VII-1-12 

VII-1-8. A Type Manager Makes the Object Appear as a Black Box VII-1-13 

VII-1-9. Linear Address Space and Domain VII-1-15 

VII-1-10. An Object's Active and Passive Version VII-1-16 

VII-1-1 1. Passive Store Unifies All Nodes in a BiiN™ System VII-1-17 

VII-1-12. A Stored Object VII-1-19 

VII-2-1. The Organization of Memory in a BiiN™ sytem Vn-2-3 



xxxvi Contents 



rKE-LfUVUl-N AK I 



VII-2-2. Passive Store VII-2-4 

VII-2-3. Physical Memory is Divided into Pages VII-2-4 

VII-2-4. Active Memory Uses Both RAM and Disk VII-2-5 

VII-2-5. The Object Table and Object Based Adress Translation VII-2-6 

VII-2-6. A Valid Virtual Address VII-2-7 

VII-2-7. Active Virtual Memory, Jobs, Nodes and SROs VII-2-8 

VII-2-8. Garbage Collector VII-2-11 

VII-4-1. Attribute Structure VII-4-2 

VII-4-2. An OS Attribute VII-4-4 

VII-5-1. Algorithm That Controls Garbage Collection VII-5-4 

VII-7-1. System Configuration VII-7-3 

VII-7-2. Booting a Node VII-7-4 

VII-7-3. Creating Configurable Objects VII-7-5 

VII-7-4. Simple Attach VII-7-7 

VII-7-5. Attaching to a Dependent Software Service VII-7-7 

VII-7-6. Back Attachment of a Dependent Software Service VII-7-8 

VII-7-7. Compound Attachment VII-7-8 

VII-7-8. System Configuration Objects VII-7-9 

VIII-1-1. A Network of BiiN™ Nodes VIII-1-3 

VIII- 1-2. The Hierarchical Structure of the Qearinghouse VIII- 1-7 

VIII-1-3. Three Different Communication Methods VIII- 1-9 

VIII-1-4. Single and Multiple Activation Model VIII-1-12 

VIII-1-5. Partial View of a Node's Directory Structure VIII-1-15 

VIII-2-1. General Model of Communication Using RPCs VIII-2-3 

IX-1-1. Device Environment IX-1-3 

IX- 1-2. Device Driver using the I/O messages Mechanism IX-1-6 

IX-1-3. Quster Server, Clusters and shared queues IX-1-9 

IX- 1-4. Device Driver with the Shared Queues Mechanism IX- 1-10 

IX-1-5. I/O shared queues Data Transfer Mechanism IX-1-1 1 



Contents xxxvii 



PRELIMINARY 



List of Tables 



rv-l-l. Devices and Supported Access Methods IV-1-5 

IV-1-2. Common I/O Operations IV-1-6 

IV-1-3. Selected Byte Stream Access Method Calls IV-1-7 

IV-1-4. Selected Record Access Method Calls IV-1-8 

IV-1-5. Selected Character Display Access Method Calls IV- 1-9 

IV-4-1. Terminal Attributes IV-4-5 

IV-5-1. Window Attributes IV-5-6 

IV-6-1. Implementation of Spool Device Attributes IV-6-6 

IV-6-2. Getting and Setting Print Properties IV-6-10 

IV-6-3. Executing Print and Spool Tasks IV-6-11 

IV-7-1. Accessing Stream and Structured Files IV-7-9 

IV-7-2. File Access Modes IV-7-9 

IV-8-1. Index Performance Considerations IV-8-5 

IV-9-1. Operation Status Record IV-9-11 

IV-10-1. Compatibility of Locks IV-10-6 

IV- 10-2. Lock Modes for Opened Device Locking IV-10-12 

IV-11-1. Interaction of DBMS Calls IV-11-10 

V-3-1. Built-in Control Commands V-3-5 

V-3-2. Built-in Runtime Commands V-3-6 

V-3-3. ArgumentTypes V-3-8 

V-3-4. Control Options for Runtime Commands V-3-10 

V-6-1. Examples of Numeric Formatting V-6-6 

V-6-2. Examples of Date Formatting V-6-7 

V-6-3. Default Screen Field Formats V-6-7 

V-6-4. Control Keys V-6-16 

V-6-5. Application Keys V-6-18 

V-6-6. Information Keys V-6-19 

V-8-1. Standard Report Default Formats V-8-8 

VI-1-1. Process Globals Entries VI-1-11 

VI-1-2. Local Event Values VI-1-16 

VII-5-1. Key GCOL Parameters VII-5-3 

VII-5-2. GCOL Parameters to Start and Stop Special GCOL VII-5-4 

VIII- 1-1. Distribution vs. Multiprocessing vs. Networking VIII- 1-4 



xxxviii Contents 



rUKLlMlINAKY 



Parti 

Introduction 



This part of the BUN™/ OS Guide provides important concepts and basic programming tech- 
niques that are used throughout the system and throughout this manual. You should read these 
chapters before reading any subsequent chapters in this guide. 

The chapters in this part are: 

Concepts Provides an overview of the OS. 

Services Areas and Services 

Describes the organization of OS packages into service areas and services. 

Ada Programming Techniques 

Contains common Ada programming teclmiques used with system caUs. 
(A fumre release will add a chapter to describe C programming techniques 
used with system calls.) 
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This chapter provides an overview of the BiiN operating system (OS) for BiiN computers. 
It discusses: 

• The functionality of the BiiN™ OS relative to other well-known operating systems such as 
VAXA^MS and UNIX systems 

• The object-oriented architecture of the BiiN™ OS. 

TM 

The BiiN OS is accessed using System Services. These services provide a variety of opera- 
tions. 



1-1.1 BiiN™ OS Functionality 

The OS is made up of logical groups of BiiN™ Ada packages. Each package contains system 
caUs to the BiiN OS. These services support and protect applications. These applications 
can be: 

multiprocessing Providing a common queue of processes for execution by one of many 
CPUs 

fault tolerant Giving nearly continuous service that protects against accidental or mali- 

cious destruction of information 

transaction processing 

Ensuring the integrity of system and application disk storage 

distributed Supporting location-independent processing, local area networks, circuit 

switched networks, and public packet switched networks. 

In addition, there are several other important features and functions discussed in this chapter. 

1-1.2 Transparent Multiprocessing with Multiple Processors 

A single BiiN™ node can have multiple processors that share a common addressable memory. 
Also, multiple computing nodes can be connected into a single distributed system that shares 
data and resources between nodes. See Figure I- 1-1. 
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Figure I-l-l. Networked, Distributed, Multiprocessing Nodes 

With the strategy employed by other systems, it's difficult for different processes to share 
memory (in particular, program variables). 

• There's no CPU support to efficiently synchronize access to shared data from multiple 
processes. 

• There aren't primitives to help a scheduler make the right scheduling decisions. The 
scheduler doesn't know when processes are working on the same task and should be 
scheduled together. 

The BiiN™ OS supports the CPU with low-level primitives that handle multiprocessing. Un- 
like most computer systems on the maricet today, BiiN™ systems have been designed — from 
the VLSI-component level to the OS level — ^to support multiple processors. 

Figure 1-1-2 shows how the dispatcher handles multiprocessing. 
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Figure 1-1-2. How the Dispatcher Handles Multiprocessing 

• A single processor is self-dispatching at a dispatching port. 

• Synchronization and communications use high-level instructions: 

- semaphore instructions, 

- communication port instructions, and 

- a dispatching port instruction. 

• The multiprocessing is transparent to users. 

• Low-level scheduling (dispatching of processes) is performed by the CPU, with no direct 
OS intervention. All CPUs share a common queue of processes, and the work load is 
evenly shared among all CPUs. 

• The CPU provides synchronization instructions. A synchronization CPU instruction can 
suspend a process while allowing other processes to run. This is done without OS inter- 
vention. Synchronization instructions such as semaphore locking and imlocking that 
suspend and release a process are much less cycle-intensive than test-and-set instructions 
that keep chewing up cycles. 

• Computations are done as jobs. Initially, a job has one process. Your program can create 
more processes in the same job. All processes in the same job can share the same address 
space (for example, the same global program variables). The OS scheduler schedules jobs 
rather than processes; it schedules jobs into and out of the dispatching mix based on exter- 
nal priorities and resource constraints. It is quite possible for all the processes of a single 
job to be simultaneously executing — each on a different processor. 
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1-1 .3 Fault-Tolerant Computing 

In existing computer systems, protection mechanisms are very limited and have changed little 
in the last 20 years. If any application or service makes an addressing error, it can overwrite or 
otherwise corrupt data (or code) in many other parts of the system. Finding an error is difficult 
because almost any application or service could have caused the error, not just the module that 
detects the error. Because errors are not confined to one module or data structure, system 
reliability is limited, and the system becomes less reliable as its software becomes more com- 
plex. 

The BiiN™ OS detects errors at their source (or, at minimum, nearby) and limits the damage 
that any one program can cause. The hardware and the OS software work together to make 
addressing violations impossible; no service can access code or data outside its protected ad- 
dress space. 

TM 

The non-stop, fault-tolerant engineering of the BiiN OS relies on the concept of a 
confinement area within which an error is contained at the time of detection and repair. If a 
bug is detected, then the damage is known to be confined to the address space accessible to 
that program. 

TM TM 

The BiiN OS supports hardware fault tolerance. The BiiN Series 20140 Hardware System 
Description and the BiiN^ Series 60/80 Hardware System Description describe hardware fault 
tolerance. 

OS support for hardware fault tolerance includes: 

• You (or your system administrator) can choose a level of hardware fault tolerance for your 
particular system configuration. 

• You can monitor hardware operations for potential failures. 

• You can configure redundant hardware to step in, for example, if a board fails. The 
hardware-controlled "stepping in" occurs without interrupting your normal servicing. 

Your system administrator determines policy. For example, if a board goes out and the system 
recovers, decisions are required: 

• Should the system maintain the same level of fault tolerance and run with fewer proces- 
sors? 

• Or, should the level of fault tolerance be set lower so that checking occurs without recovery 
and all processors continue functioning? 

The BiiN™ OS lets you control the outcome of these decisions. It also supports fault tolerance 
by providing built-in redundancy. Figure 1-1-3 shows how the BiiN™ OS aids fault tolerance. 
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Figure 1-1-3. How the BiiN™ OS Aids Fault Tolerance 



• Volume sets can be mirrored. If a file exists on a mirrored volume set, the file exists on 
two disks. 

- If one disk or I/O controller goes down, the data on a mirrored volume set remains 
accessible. 

- Mirroring can be re-established (online and transparent to applications using the disk) if 
the bad disk comes back up. 

• Files and directories can be logged. Everything that happens to the file or directory can be 
written to a log. After a disk crash, the file or directory can be restored from a previously 
saved back-up copy. Once restored, the file can be rolled forward to a specific date/time 
based on log entries. 

• Incomplete transactions are undone. If a system crash occurs before a transaction is com- 
pleted, aU effects of the transaction are automatically undone. (See the next section for 
more on transactions.) 
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• Communication is automatically rerouted. The nodes in a multi-node system can be con- 
nected with redundant connections controlled by separate I/O controllers. If a connection is 
lost, communication gets rerouted. 

1-1.4 Transaction Processing and DBMS Support 

Transactions are a familiar concept to most mainframe DBMS users. Basically, transactions 
group file writes so that either all occur at once, or none occur at all. 

Although transactions are primarily used to protect data in files, the BiiN™ OS extends the 
concept of transactions to include directories and other resources managed by non-filing ser- 
vices. 

Most conventional systems build transactions into a database layer: 

• To use transactions, programmers are forced to learn a DBMS. Existing files and programs 
must be converted to DBMS formats. This is acceptable for programmers who are familiar 
with query languages such as SQL. It's not, however, always the best solution for 
programmers who want quick record access using the existing files of their ported applica- 
tions. 

• Because conventional OS filing does not provide the right structures for database systems, 
transactions build into a database layer can be hard to implement DBMS software must 
build file structures (for example, a file cache on top of virtual memory) using the primi- 
tives supplied by the OS. This is inefficient. 

Transactions and other DBMS filing fiinctions are built into the BiiN™ OS. The BiiN™ filing 
service offers: 

UNIX-style byte stream files and special BiiN™ record files 

hashed or b-tree indexes for record files 

sequential, relative, clustered, hashed, and unordered file organizations 

one or more key values (of multiple data types) for an index key 

support for null values 

true variable-length records and true variable-length fields within a record 

integration with the BiiN™ Data Definition Facility (known in other systems as a data 
dictionary facility). 

record-level locking integrated with transaction-support 

different levels of consistency including level 3 as defined by IBM SYSTEM R. 

sorting and merging large collections of records 

database joins, projects, and selects 

logging, integrated with backup/restore, so that a file can be backed up and later roUed 
forward from a log. 

A major performance advantage of the BiiN™ file service is file buffering that uses a file cache 
in a special RAM-based stable store. Several configurations are available. For example: 

• A configuration that is fuUy duplicated, ECC protected (with spare-bit), battery-backed-up, 
with each component powered by separate power supplies and separate batteries 
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• A configuration that is accessible from two busses (in case one bus goes down). 

Because of the reliability of the stable store, writes to disks may be delayed indefinitely. Com- 
pleting a transaction or closing a file may not cause a disk write. 

1-1.5 Computing in a Distributed Environment 

When large timesharing machines in the 1970s were shared by many users, data and file shar- 
ing was easy. However, CPU cycles were hard to come by. 

Today anyone can have a PC, workstation, or other node in a small local area network attached 
to a mainframe or mini. CPU cycles may be plentiful, but program and data sharing between 
nodes is complicated, often requiring communications, file transfers, and remote file access. 
This is tricky to do without a knowledge of file naming conventions and network protocols. 

The BiiN™ OS protects users from the complexity of inter-node communication between ser- 
vices. For example, you can type a command at your home node and simultaneously run 
programs at other machines that are accessing files from still other machines. The combined 
file space of aU nodes looks like a single file space. 

• When a program runs, it sees the scone current directory and home directory regardless of 
the node it runs on. 

• There is no special naming for remote files. A file stored in your directory with the name 
suppliers might be on any node on a distributed system. The program that accesses the 
file (regardless of the node the program executes on) sees the same interface to the OS file 
service. 



• 



• 



You control where your program is run, but your system administrator controls which 
nodes you can run on, and the quality-of-service you'll get on each of these nodes. 

You can control the location of your files (and other programming resources) and find out 
where files needed by your program are located. For a program with lots of I/O, it is often 
more efficient to run the program on the same node as the data, rather than bring the data to 
the node running the program. 



1-1.6 Support for UNIX and ISO Standards 

The BiiN™ OS supports many industry standards, including: 

• System V Interface Definition for UNIX systems 

• Commimication Protocols: 

- ISO Transport Qass 4 

- ISOFTAM 

- X.25 

- HDLC 

- LAN 802.3 

• IEEE Floating Point 
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These standards allow you to easily integrate your existing hardware and software into BiiN™ 
systems. Since UNIX System V-compatible calls are supported, you can port your existing 
UNIX applications easily. 



1-1.7 Services for High-Function Appiications 



Many systems provide two address spaces within a process — one for an application and one for 
the OS. Filing, program execution, and other supervisory routines reside in a monolithic ker- 
nel. This is known as the two-space view. 

As applications increase in function, they are becoming more complex. To build these high- 
function applications, supporting services such as database, forms, and communications are 
required. The dilemma faced by traditional two-space operating systems is how to fit these 
supporting services to the OS. 

There are three approaches to adding a service to a two-space operating system: 

• Put the supporting service in the address space of the OS. The result? The OS increases in 
size and complexity. The introduction of a new service (from which the rest of the OS 
can't be protected) results in lower OS reliability, and therefore reduced system reliability. 
Typically, this is how communications is implemented. 

• Put the supporting service in the address space of the application. This is often impossible 
because the supporting service needs to access data and operations that the application isn't 
allowed to access. It becomes difficult to track down errors: an apparent malfimction in a 
supporting service could be caused by a bug in the supporting service or the application 
program. The bug might be as simple as using an uninitialized index variable to store into 
an array. 

• Put the supporting service in its own address space. This is the approach often taken by 
mainframe DBMS software — it means putting the DBMS in its own process. The result? 

- Invoking the supporting service from application programs can be awkward. Instead of 
a simple call/return mechanism, costly inter-process communication must be used. 

- Processing bottlenecks occur when different applications make requests at the same 
time. 

- There are problems in accounting, resource control, and protection. How does the re- 
questing application get charged for its use of the service? How does the service know 
the identity of the requestor? How does the service prevent one application from 
swamping it with requests, at the expense of other applications? 

TM 

In contrast, the BiiN solution gives each supporting service its own address space within a 
process. This is known as the n-space view. Calls to a service are synchronously executed by 
the user process itself. However, the data and operations of the called service are protected 
from the caUer by using a separate address space for the service. 

Today's high-function applications often need to use many supporting services. This demands 
more than a smiple 2-space view of the world. The BuN OS provides a uniform call/return 
mechanism that can be used by all services in the system — ^from supervisory routines to ap- 
plications. Each service can have its own call stack, and can be used by the application the 
same way you use an existing service (such as an OS filing service). This increases system 
speed, reliability, and ease-of-use. Basically, the key to imderstanding the n-space view is 
protection. 
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A traditional "onion skin" view of the BiiN™ OS doesn't convey how programs and data are 
protected by the system. Each system service can have an invincible boundary of protection 
built around the address space it occupies. 

Compared to other operating systems: 

• The BiiN™ OS is fast. Within a single process, each service can execute in its own address 
space. A single call instruction takes care of switching address spaces. This form of call is 
faster than most supervisor call instructions on other machines. 

TM 

• The BiiN OS is reliable. An invoked service's access to the caller's address space is 
limited to just the parameters passed by the caller. A service is protected from an applica- 
tion, and an application is protected from a service. One service can invoke another service 
using the same calling conventions. 

• The BiiN™ OS is easy-to-use. A service executes in a user-invoked process. It does not 
have to provide its own protection, resource control, and accounting mechanisms. With 
less code, and fewer primitives to learn, you can concentrate on the service's operations. 

1-1 .8 Transparent Resource Management for Easy 
Programming 

Many operations of the BiiN™ OS are executed transparently using virtual memory and file 
buffering (with a little help from hardware): 

• You can invoke and run several programs simultaneously. Each program runs as a job and 
can appear as a window on your terminal screen. 

• Job scheduling, memory space allocation, and file buffer space are handled automatically. 

For example, the total of all address spaces for a job might be 2 MB, but your job really only 
needs 500 KB of primary memory to run. Here's what happens: 

• When a job accesses a page not present in primary memory, a fault (invisible to the job) is 
generated and the page gets swapped in. 

• When the hardware reports that a page in primary memory has not been recently accessed, 
the page is swapped out if changed previously. 



1-1.9 Getting Real Time Data 



Suppose you need to monitor the movement of robot vehicles on the floor of a factory. You 
need a way to sense their movement, perform computations, and teU them what to do next — in 
real time. You don't want a lot of memory and I/O oveihead to do this; the robots would be 
crashing into each other because of the time delays. 

The BiiN™ OS stays out of the way and lets the hardware do much of the work: 

• As your program executes, application-defined interrupt handlers are invoked without OS 
intervention. 

• Low-level scheduling and synchronization is handled by the CPU. 

• Low-level scheduling is priority-based with preemption. 
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Consider an interrupt procedure that gets invoked due to a signal from a robot vehicle. The 
procedure might do some processing and then signal a semaphore to cause a suspended real- 
time process to run. The OS just stays out of the way and lets the hardware do the work. 

The BiiN™ OS supports real-time programming: 

• Your system administrator can define different real-time scheduling levels and grant access 
to specific users/programs for a particular level. 

- A real-time program can run at a high-priority level. 

- The job remains in the dispatching mix (managed by hardware), and bypasses the OS 
scheduler. 

• A real-time program can spawn multiple processes within the same job. Each process can 
run at a different priority. 

- Processes can communicate information using shared memory and can synchronize 
using semaphores. 

- The hardware also provides a message-passing mechanism (ports) that uses Send and 
Receive instructions. Like semaphores, the port mechanism is integrated with 
hardware dispatching. 

• A real-time job can run with its entire address space in primary memory (that is, in frozen, 
non-relocatable memory). When this occurs, the job wiU not encounter any virtual memory 
faults. 

• Real-time data collection programs can quickly stream large amounts of data to and from 
disk, with minimal disk head movement. 

- The filing service lays out files contiguously on disk using extents. 

- The file buffer management strategy is read-ahead and write-behind. 

- Indexes and file records can be placed on different physical disks. 

1-1.10 System Administration and the Clearinghouse 

What is a "aearinghouse?" Basically, it's a location-server database that lets a system ad- 
ministrator easily control and administer a network: of nodes. The Clearinghouse maintains a 
record of which objects and IDs are at which nodes. 

With most distributed computer systems, it's difficult to administer networks that consist of 
more than a handful of nodes: 

• To add a new node to a network, the system administrator has to modify configuration data 
for all nodes. 

• Additional modifications are required if a node is moved from one local network to 
another. 

• Often, a file name previously used to access a file on a node must be changed when the 
node is relocated. 

• If a node goes down with a bad board, there is no way to easily move the node's disk to 
another node. 
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To remedy this situation, the BiiN OS maintains a database of inforaiation about nodes, 
users, volume sets, and distributed services — ^the aearinghouse. 

• The system administrator adds information using a Qearinghouse utility. 

• The information is duplicated on a few key nodes, and is available to all nodes. 

• When node 1 needs information about node 2, it asks the Qearinghouse. 

• The system administrator can select which nodes have Qearinghouse data, and which por- 
tion of the total Qearinghouse database they contain. 

Suppose, for example, that node 1 contains a volume set (a logical disk). Your system ad- 
ministrator can move the volume set from node 1 to node 2 (perhaps on a different local 
network) by changing the I/O configurations of nodes 1 and 2. This does not affect users and 
programs that previously accessed files on the volume set. All file names remain the same, and 
appear as if they are on your home node. 



iTM 



1-1.11 BiiN" OS Architecture 

System Services consist of several distinct service areas such as I/O Services. These service 
areas consist of one or more system services such as the filing service. Each service controls a 
certain part of the system, and all services interact. 

Figure 1-1-4 illustrates the relationship between services, packages, and calls. 



SERVICE 
AREA SERVICE PACKAGE CALL 







EXAMPLE: A I/O Services 

O filing service 

U File_Admin 

— Create_file 

Figure 1-1-4. The OS Interface is Made up of Services, Packages, and Calls 
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1-1.12 Some Basics 



Each service executes in its own address space. This space is broken up into individual 
protected segments of memory called objects. One way to think of this decomposition is to 
imagine a box of building blocks. The blocks — triangles, squares, rectangles, and so 
forth — can be combined to form different structures such as bridges and houses. 

One structure (for example, a bridge) is independent from another structure (for example, a 
house), yet all structures are composed of the same basic blocks. In this analogy the dif- 
ferently shaped blocks are objects y and the structures correspond to services. All blocks of the 
same shape have the same characteristics. Similarly, every object has a "type", and all objects 
of the same type have the same characteristics. 

An object is sometimes referred to as a system object to distinguish it from a BiiN^ Ada object. 
(A BiiN™ Ada object is a variable or construct — see the BUN™ Ada Language Reference 
Manual.) However, when you see the term object used in this manual, it refers to system 
object unless otherwise specified. 

Think of an object as a resource managed by a service. For example, a file is represented as an 
object of type "file" that is managed by the filing service. Each individual service controls 
access to its objects. 

Existing operating systems provide two mechanisms to name files, I/O chaimels, users, 
processes, and nodes (that is, their "objects"): 

names Symbolic names that you assign to objects, and 

identifiers Binary digits that provide an efficient means for a program to identify an 

object. 

Each "object" in existing systems usually can be referenced by an identifier. In general, the 
format for identifiers of each object type is different — an I/O channel identifier has a different 
format than a user identifier. The mapping of names to identifiers is also different for each 
object type. 

In contrast, the BiiN™ OS supports one form of identifier (actually in hardware) for its objects. 
This allows identifiers for different object types to be distinguished. It also permits universal 
name mapping. 

BiiN™ OS identifiers serve several functions: 



• 



• 



They contain the addresses of the objects they coirespond to (that is, they function as 
conventional pointers). 

They specify the rights of the calling program to use the objects managed by a service. 

• They can be used to fmd out the type of object they reference. 

^ TM 

This manual uses the term access descriptor or AD to refer to the object used by the BiiN OS. 
Figure 1-1-5 shows how ADs specify the calls you are allowed to make. 
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A caller with my_AD can Open, Create, Rename, or Delete. 
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A caller with your_AD can only Open the directory. 

Figure 1-1-5. ADs Provide Access and Protection to Services 

The caller withmy_AD can make the calls Open, Create, Rename, and Delete. The 
directory service processes those calls. The identifier my_AD controls the caller's access. 
Similarly, the caller with your_AD can only Open the directory (for reading). 

1-1.12.0.1 What Is A System Object? 

A system object is a protected segment of memory. 

A system object is distinct from a BiiN^ Ada object (an entity that contains a value of a certain 
type). Whenever you see the unqualified use of the temi object in this manual, it means system 
object. 

There are many types of objects, including file, directory, and pipe objects. Each type of 
object can have multiple instances (for example, there might be several instances of an object 
of type "pipe" in memory at any particular moment). 
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1-1.12.0.2 How Are System Objects Protected? 

System objects are protected from unauthorized reference. Access to an object is restricted to 
software with a "need to know" about the object. Access can be controlled at the level of 
individual data structures and procedures through the use of an AD. Each call requires the use 
of one or more ADs. 

Each memory word has a tag to indicate whether or not it is an AD. ADs can only be manipu- 
lated in controlled ways and with special instructions, all designed to make accidental or mali- 
cious violations of the object protection mechanism impossible. 

ADs are also protected pointers to data structures and correspond to the pointer values sup- 
ported by some programming languages. For example, a BiiN Ada access value can be 
represented as an AD. ADs are also synonymous with the protected pointers called 
capabilities provided by some object-oriented computer architectures. 

There can be multiple ADs for an object, and different ADs can grant different access rights. 
There are two classes of access rights: 

type rights There are three type rights. Each right corresponds to a set of operations 

that manipulate an object. The type rights used by the operating system 
are usually mapped to use, modify, or control. A caller can have any com- 
bination of the three type rights. 

rep rights There are two representation ("rep") rights. They are used to control ac- 

cess to the contents of an object (using CPU instructions directly). These 
are only important to you if you're creating your own service. See "Type 
Manager Services." 

An understanding of type rights is helpful for most OS programming. Figure 1-1-6 shows an 
AD with type rights. 
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Type Rights 



Figure 1-1-6. An AD Showing Type Rights 



Type rights are: 
use 

modify 
control 



Required to retrieve information from an object, without changing it Cor- 
respond to a set of operations provided by the service that manages the 
object. 

Required to modify an object, without destroying it or changing its basic 
nature. Correspond to a set of operations provided by the service that 
manages the object. When compared with use rights, modify rights give a 
user additional operations to manipulate the object 

Required to destroy or restructure an object 



Different services sometimes map their rights to variant names. For example, use 

rights — ^needed to read a file — ^in the filing service corresponds to the same level of access as 

list rights — ^needed to list the contents of a directory — in the directory service. 

Two programs can have ADs for a shared object with one having only use rights and the other 
having only modify rights. An AD can also be null, indicating that it references no object For 
example, objects can be linked together in a list, with each object containing an AD that 
references the next list element. The last object in the list would contain a null AD in the link 
field, indicating that there are no more list elements. 

ADs can be freely copied. It is normal to pass a copy of an AD to a called subprogram to 
specify an object as a parameter. The rights on an AD are often restricted when it is copied: 
some rights are removed from the copy, leaving only those rights needed by the subprogram 
that receives the copy. 
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Adding rights to an AD is called amplifying those rights. Only the service that manages the 
object is allowed to amplify its rights. See "Type Manager Services" for details. 



Concepts 1-1-17 



rKlil-fllVlll> AK X 



1-1-18 Concepts 



PRELIMINARY 



SERVICE AREAS AND SERVICES 



2 



Contents 

Service Areas 1-2-3 

Support Services 1-2-3 

Utility Service 1-2-3 

Object Service 1-2-4 

Transaction Service 1-2-4 

Message Service 1-2-4 

Directory Services 1-2-5 

Naming Service 1-2-5 

Protection Service 1-2-5 

I/O Services 1-2-5 

Basic I/O Service 1-2-6 

Character Terminal Service 1-2-6 

Print Service 1-2-6 

Spool Service 1-2-6 

Filing Service 1-2-6 

Database Support Service 1-2-7 

Data Definition Service 1-2-7 

Volume Set Service 1-2-7 

Basic Disk Service 1-2-7 

Basic Streamer Service 1-2-8 

Null Device Service 1-2-8 

Human Interface Services 1-2-8 

Command Service 1-2-8 

Form Service 1-2-8 

Report Service 1-2-8 

Program Services 1-2-9 

Concurrent Programming Service 1-2-9 

Scheduling Service 1-2-9 

Timing Service 1-2-10 

Resource Service 1-2-10 

Program Building Service 1-2-10 

Monitor Service 1-2-11 

Type Manager Services 1-2-1 1 

TM Object Service 1-2-11 

TM Transaction Service 1-2-11 

TM Concurrent Programming Service 1-2-12 

Configuration Service 1-2-12 

Custom Naming Service 1-2-12 

Backup Service 1-2-12 

Distribution Services 1-2-13 

Clearinghouse Service 1-2-13 

Service Areas and Services 1-2-1 



rKKLlMlJNAKY 



RPC Service 1-2-13 

Transport Service 1-2-13 

Device Services 1-2-14 

Device Driver Service 1-2-14 

Shared Queue Service 1-2-15 

Asynchronous Communication Service 1-2-15 

Mass Storage Service .1-2-15 

SCSI Service 1-2-15 

Subnet Service 1-2-15 

HDLC Service .1-2-16 

LAN Service .1-2-16 



1-2-2 Service Areas and Services 



PRELIMINARY 



This chapter briefly describes the OS as a collection of services and service areas. A service is 
simply a logical collection of packages. A service area is a logical collection of services. 
Services and service areas define a logical organization of the OS, for documentation and 
learning purposes. 

Often, a service manages one or more closely related object types. For example, the naming 
service manages directories, open directories, name spaces, open name spaces, and symbolic 
links. 

Packages listed in this chapter can be found in the BiiN^/OS Reference Manual. 

1-2.1 Service Areas 

There are eight service areas: 

Support Services Often-used basic services, including system definitions, utility packages, 
object management, transactions, and messages. 

Directory Services Manages directories, directory lists (name spaces), symbolic links, and the 
authority lists and IDs used to protect directory entries. 

I/O Services Provides byte-stream, record, and character display I/O. Manages files, 

character terminals, character terminal windows, printers, spool queues, 
and other I/O devices. 

Human Interface Services 

Provides commands, forms, and reports used to interact with users. 

Program Services Provides various program execution services including concurrent pro- 
gramming, scheduling, timing, resource control and accounting, and 
program monitoring. 

Type Manager Services 

Provides special OS interfaces for trusted type managers, including access 
to global memory and participation in system configuration. 

Distribution Services 

Provides services used to build distributed applications that execute trans- 
parently in a distributed BiiN™ system. 

Device Services Provides services used to build new device drivers and device managers. 

1-2.2 Support Services 

Support Services contains: 

utility service 
object service 
transaction service 
message service. 

1-2.2.1 Utility Service 

Manages system definitions, text strings, and long integers. 

Long_Integer_Def s 

Defines types and calls for 64-bit long integers. 
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Machine_Cocie_Insertion 

Provides useful operations that map to inline CPU instnictions. 

String_List_Mgt 

Provides operations on string lists. 

System Provides implementation-defined (as opposed to Ada-defined) types and 

constants. 

S y s t em_D e f s Provides common definitions used throughout the OS. 

System_Exceptions 

Defines common exceptions. 

Text_Mgt Provides operations on text records. 

1-2.2.2 Object Service 

Manages objects, access to objects, and storage of objects. 

Ac c e s s_Mgt Interface for checking or changing rights in access descriptors. 

At t r ibut e_Mgt 

Provides a way to define general-purpose operations supported by multiple 
object types or objects, with different type-specific or object-specific im- 
plementations. 

Ob j ect_Mgt Provides basic calls for object allocation, typing, and storage management 
Defines access rights in ADs. 

Passive_Store_Mgt 

Provides a distributed object filing system. 

1-2.2.3 Transaction Service 

Manages transactions. 

Transact ion_Mgt 

Provides transactions used to group a series of related changes to objects 
so that either all the changes succeed or all are rolled back. 

1-2.2.4 IVIessage Service 

Manages system and application errors and messages. 

History_Services 

Contains calls for using a job's history log files. See also the built-in ' ' 
. history_log" commands, and tiie : : history control option, in the 
Command Language Executive Guide. 

Incident_Def s 

Defines incident and message types. 

Me s s age_Adm Manages message files used by Message Services. 

Message_Services 

Provides calls to write messages from message files, message stacks, or 
message blocks. 

Message_Stack_Mgt 

Manages a process's message stack. 

Msg_Object_Def s 

Defines the four message objects used by the operating system. 
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System_Error_Recording 

Provides calls to record errors in a system log file. 

1-2.3 Directory Services 

Directory Services contains: 

naming service 
protection service. 

i-2.3.1 Naming Service 

Manages directories, lists of directories, and symbolic links. 

Direct or y_Mgt 

Manages directories and directory entries. 

Name_Spa ce_Mgt 

Provides caUs to manage name spaces Gists of directories). 

Syitibolic_Link_Mgt 

Provides calls to create, list, and identify symbolic links. 

1-2.3.2 Protection Service 

Manages authority lists, IDs, and user profiles. 

Author it y_List_Mgt 

Provides calls to manage authority lists and to evaluate a caller's access 
rights to objects protected by authority lists. 

Identification_Admin 

Provides calls to create and modify IDs, and to modify an ID's user 
profile. 

Identification_Mgt 

Provides operations to manage IDs and ID lists. 

Us er_Mgt Provides calls to manage a user's protection set and user profile. 

1-2.4 I/O Services 

I/O Services contains: 

basic I/O service 
character terminal service 
print service 
spool service 
filing service 
database support service 
data definition service 
volume set service 
basic disk service 
basic streamer service 
null device service. 
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1-2.4.1 Basic I/O Service 

Manages byte stream I/O, common I/O definitions, and byte stream files. 

Byte_Stream_AM 

Provides device-independent I/O using streams of b5^es. 

De vice_Def s Declares common I/O types, constants, and exceptions. 

S imp 1 e_F i 1 e_Adini n 

Manages stream files. 

1-2.4.2 Ciiaracter Terminal Service 

Manages character terminals and character terminal windows. 

Character_Display_AM 

Provides device-independent 1/0 to character display devices such as 
printers, plotters, and windows on character and graphics terminals. 

Character_Terminal_Mgt 

Manages character terminals. 

Terminal_Adinin 

Provides administrative operations for terminals. 

Terminal_Def s 

Defines constants, types, and exceptions used by the terminal service 
packages. 

Terminal_Info 

Manages terminfo entries. 

Window_Services 

Provides windows on character and graphics terminals, including pull- 
down menus. 

i-2.4.3 Print Service 

Manages printers. 

Printer_Acimin 

Provides administrative operations for printers. 

1-2.4.4 Spool Service 

Manages spool queues. 

Spoo l_De f s Declares types and constants used by spooling packages. 

Spool_Device_Mgt 

Manages spool devices. 

Spoo l_Queue_Admin 

Provides administrative caUs for spool queues. 

i-2.4.5 Filing Service 

Manages files and records. 

File Admin Administers files. 
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F i 1 e_D e f s Provides declarations used for filing and indexing. 

Re CO r d._AM Provides device-independent record I/O. 

1-2.4.6 Database Support Service 

Provides advanced or trusted interfaces to support DBMSs (database management systems). 

Join_Interface 

Provides support for block joins of records from multiple indexed files or 
record stream devices. 

Record_Processing_Support 

Provides specialized support for processing collections of records. 

Sort_Merge_Interface 

Sorts and merges records from one or more input devices into a single 
ordered record stream. 

Trusted_Record_Processing_Support 

Provides specialized support for processing collections of records using 
user-supplied routines. 

1-2.4.7 Data Definition Service 

Manages data definitions. 

Data_Def inition_Mgt 

Manages data definitions (DDefs). This interface is a symbol table for the 
development of a DDef compiler. 

DDF_Utility_Support 

Defines DDef properties used by services other than the data definition 
service. 

Field_Access Provides buffer access to fields in records that reference data definitions 
(DDefs). 

1-2.4.8 Volume Set Service 

Manages volume sets. 

Vo lume_S e t _Adini n 

Manages volume sets. 

Vo lume_S e t_D e f s 

Defines types, constants, and type-checking for volume sets and volume 
set disks. 

VSM_D i s k_Admin 

Provides administrative and information calls for volume set disks. 

VSM_Disk_Support 

Provides calls to initialize a volume set disk, verify the allocated space on 
a disk, and remove a volume from a volume set disk. 

1-2.4.9 Basic Disl< Service 

Manages basic disks. 

Ba s i c_D i s k_Mgt 

Manages basic disks. 
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1-2.4.10 Basic Streamer Service 

Manages basic streamers, representing streaming tape drives. 

Basic_Streamer_Mgt 

Manages basic streamer devices. 

1-2.4.1 1 Null Device Service 



Manages null devices, used as "bit buckets" that discard all output and provide an immediate 
end-of-file for input. 

Nuldev_Mgt Manages null devices. Null devices support byte stream I/O and record 
VO. 



1-2.5 Human Interface Services 

Human Interface Services contains: 

command service 
form service 
report service. 

1-2.5.1 Command Service 

Supports application-defined commands and command sets, and manipulation of command 
language variables and of command help texts. 

CL_Def s Contains declarations used by the command service, for processing com- 

mand language (CL) arguments and variables. 

Coiranand_Execut ion 

Contains a procedural interface to command execution. 

Command_Handler 

Contains operations for reading and processing program commands and 
arguments. 

Environinent_Mgt 

Contains operations to get, set, or remove local and global environment 
variables. 

He lp_Text_Adin 

Manages command and form help texts. 

1-2.5.2 Form Service 

Manages forms. 

Form_Def s Defines types and constants used by the Form_Handler package. 

Form_Handler Provides calls to process, control, and change forms. 

[-2.5.3 Report Service 

Manages reports. 

Report_Handler 

Provides calls for initializing and printing a report. 
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1-2.6 Program Services 

Program Services contains: 

concurrent programming service 
scheduling service 
timing service 
resource service 
program building service 
monitor service. 

1-2.6.1 Concurrent Programming Service 

Supports concurrent programs, programs with multiple processes or jobs executing together. 

Event_Admin Provides Establish_event_handler and Change_event_ 

state calls for administrative users, more powerful than the correspond- 
ing calls in E ve n t _Mgt . 

Event_Mgt Manages event clusters. Event clusters provide distributed communica- 

tions and software interrupts for processes. 

Job_Admin Provide a more powerful lnvoke_ j ob call for administrative users. 

Job_Mgt Provides public operations on jobs. 

Job_Type s Declares types and type rights for jobs. 

Pipe_Mgt Manages pipes. A pipe is a one-way interprocess or interjob I/O channel. 

Pipes support byte stream I/O and record VO. 

Process_Admin 

Provides more powerful Spawn_process and Set_process_ 
global s calls for administrative users. 

P r o c e s s_Mgt Provides public operations on processes. 

Process_Mgt_Types 

Declares types and type rights for processes. 

S emaph o r e_Mgt 

Manages semaphores. Semaphores can be used to synchronize concurrent 
access to shared data structures or resources. 

Session_Adinin 

Provides administrative operations on sessions. 

S e s s i o n_Mg t Provides public operations on sessions. 

Session_Types 

Declares types and type rights for sessions. 

1-2.6.2 Sciiedufing Service 

Manages scheduling of jobs and processes. 

SSO_Adinin Provides calls to create and modify Scheduling Service Objects (SSOs). 

SSO_Types Defines job scheduling classes, Scheduling Service Objects (SSOs), and 

SSO messages. Also provides a function to determine whether an AD 
references an SSO. 



Service Areas and Services 1-2-9 



1-2.6.3 Timing Service 

Manages system time, timed requests, time computations, and time format conversions. 
C 1 o c k_Mgt Manages a node ' s system clock. 

Protection_Key_Mgt 

Manages protection keys. 

T ime_Z o n e_Map 

Provides calls to map between time zones and time zone names. 

Timed_Reques t s_Mgt 

Supports the scheduling of timed requests at a node and provides access to 
the node's system clock. 

Timing_Adinin Provides calls for manipulating timed request queues and setting the local 
time zone. 

Timing_Conversions 

Provides caUs for converting between numeric representations of time and 
other representations, and for obtaining the local time zone. 

Timing_String_Conversions 

Provides calls for converting between string representations of time and 
other representations. 

Timing_Utilities 

Provides calls to inquire about timed requests. 

i-2.6.4 Resource Service 

Supports resource control and accounting. 

Re s o ur c e_Mgt Provides distributed resource management. 

Resource_Mgt_AM 

Provides the type manager's interface to resource management, including 
the resource administration attribute. 

Resource_Types 

Defines constants and types used for resource management. 

Resource_Utilities 

Implements resource accounting. 

1-2.6.5 Program Building Service 

Supports programs that build or manipulate programs, such as compilers, linkers, and debug- 
gers. 

Control_Types 

Defines a process's arithmetic controls, process controls, and trace con- 
trols. 

Debug_Support 

Supports the debugger by providing access to a process's domain object, 
static data object, instruction object, control stack, process controls, and 
other structures. 

Domain_Mgt Provides calls to check whether an AD references a domain object, an 
instruction object, a static data object, or a stack object. 
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Execut ion_Suppor t 

Supports the execution of executable objects. 

Link_By_Call Supports finding and calling an arbitrary subprogram at runtime. The sub- 
program must be in an image module or view and be interdomain-callable. 

Pr ogram_Mgt Supports program invocation and the retrieval of program-related infor- 
mation. 

RTS_Support Supports language-defined runtime systems (RTSs). 

1-2.6.6 Monitor Service 

Supports monitoring of program execution. 

Monitor_Def s Defines types used by Monitor_Mgt. 

Monitor_Mgt Manages monitors used to record information about program execution. 

1-2.7 Type Manager Services 

Type Manager Services contains: 

TM object service 

TM transaction service 

TM concurrent programming service 

configuration service 

custom naming service 

backup service. 

1-2.7.1 TIVI Object Service 

Provides object and memory operations for building advanced type managers. 

Countable_Object_Mgt 

Supports type managers of countable global objects. 

Global_SRO_Defs 

Provides access to the global SROs used to allocate global objects. 

Lifetime_Control 

Provides a trusted interface for creating and managing lifetime violations. 

PSM_Trusted_Attributes 

Defines the passive store trusted attribute. 

SRO_Mgt Provides memory management information and control of local garbage 

collection for local storage resource objects (SROs). 

Un s a f e_Ob j e c t_Mg t 

Provides special object allocation and deallocation calls. 

i-2.7.2 TM Transaction Service 

Manages transactions within a type manager. 

Local_Transaction_Def s 

Defines the per-object record used by instantiations of the Local_ 
Transact ion_Mgt generic package. 

Local_Transaction_Mgt 

Provides transaction-oriented locking for type managers of local objects. 
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TM_Transaction_Mgt 

Supports global transaction-oriented type managers that customize their 
participation in transactions. See Transact ion_Mgt for a general 
description of the transaction service. 

1-2.7.3 TM Concurrent Programming Service 

Provides concurrent programming support for advanced type managers. 

Job_Resource_Reclamation 

Supports type managers that reclaim resources when a job is terminating. 

P o r t _Mgt Provides fast interprocess communication within a job. 

Typemgr_Support 

Supports masked type managers implementing blocking operations. 

Un s a f e_P o r t _Mgt 

Provides unsafe deallocation for ports. 

Unsafe_Semaphore_Mgt 

Provides unsafe deallocation for semaphores. 

1-2.7.4 Configuration Service 

Defines how type managers configure themselves during system initialization, or dynamically 
reconfigure themselves at runtime. 

Configuration 

Provides operations for creating and modifying a system configuration. 

1-2.7.5 Custom Naming Service 

Supports custom directories and custom links. 

Cu s t omi z e d_Naine_Mgt 

Provides a call to retrieve the name mapper attribute and an . ops inter- 
face package for implementing customized name mappers. 

LinkjMgt Provides a call to return the link attribute ID. 

Standalone_Directory_Mgt 

Provides the Create_standalone_directory caU. 

1-2.7.6 Backup Service 

Supports type managers that participate in backup, logging, restore, or rollforward operations. 

Backup_Support 

Defines the backup attribute that trusted type managers can implement to 
support backup and recovery. This package is not implemented in this 
release. Its specification is included to provide design information about 
the backup service. 

Trusted_Log_Mgt 

Provides trusted type managers with caUs for writing to the system logs. 
This package is not implemented in this release. Its specification is in- 
cluded to provide design information about the backup service. 



1-2-12 Service Areas and Services 



PRELIMINARY 



1-2.7.7 Distribution Services 

Distribution Services contain: 

clearinghouse service 
RPC service 
transport service. 

[-2.7.8 Clearinghouse Service 

Manages the Clearinghouse, used to find network addresses, volume sets, and other infor- 
mation in a distributed system. 

CH_Admin Manages Qearinghouse administrators, and provides calls for ad- 

ministrators to add and delete servers, organizations, domains, and en- 
vironments. 

CH_Client Manages Qearinghouse entries and entry properties. 

CH_Support Provides calls to find out about the Clearinghouse structure, to modify 
client key, and to check access to environments. Also provides calls to 
administer an environment. 

No de_I D_Mapp i n g 

Provides calls for getting node ID and naming information. 

1-2.7.9 RPC Service 

Provides a remote procedure call (RPC) mechanism for communicating between instances of a 
service at different nodes in a distributed system. 

RPC_Admin Provides administrative RPC calls. 

RP C_Ca 1 1_S uppo r t 

Provides ftmctions for remote procedure calling. 

RPC_Mgt Provides a remote procedure call (RPC) facility used to implement dis- 

tributed services. 

1-2.7.10 Transport Service 

Provides network-independent communication between nodes. 

Comm_D e f s Contains common addressing and buffer definitions for the communication 

services. See also TM_Coiran_Def s and Subnet_Def s. 

Datagram_AM Provides service-independent datagram communications. 

DG_Filter_Mgt 

Defines datagram I/O filter functions. See also vc_Filter_Mgt for vir- 
tual circuit I/O filter functions. 

Distributed_Service_Admin 

Provides calls for building universal distributed services. 

Distributed_Service_Mgt 

Provides features needed by distributed service implementers. 

I SO_Adr_De f s Defines ISO-specific NSAP, TSAP and TCP addresses, and several func- 
tions for converting between Conim_Def s byte addresses and ISO ad- 
dresses. 
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ISO_Config_Defs 

Defines parameter records and incident codes for creating ISO transport 
services, including direct and indirect subnetworks, and gateways. See 
also the I SO_Adr_D e f s package. 

ISO_TM_Admin Provides operations to enable and disable communications tracing, and to 
get ISO-specific status informatioa 

TM_Comm_Def s Contains common definitions for transport services. See also the Comm_ 
Def s and Subnet_Def s packages. 

VC_Filter_Mgt 

Defines virtual circuit I/O filter functions. See also DG_Filter_Mgt for 
datagram I/O filter functions. 

Virtual_Circuit_AM 

Provides service-independent virtual circuit commimications. 

1-2.8 Device Services 

Device Services contains: 

device driver service 

shared queue service 

asynchronous communication service 

mass storage service 

SCSI service 

subnet service 

HDLC service 

LAN service. 

i-2.8.1 Device Driver Service 

Provides interfaces used to build device drivers. 

CP_1 0_De f s Contains declarations used for communicating with Channel Processors 
(CPs). 

CP_Mgt This package defines the types used in communicating with a Channel 

Processor (CP). This includes the format of various data structures used 
by a Channel Processor. Furthermore, the Send_to_CP operation is 
defined here. It forwards an I/O message to a Channel I*rocessor for ser- 
vice. 

CP_Resources Defines the CP resources attribute. 

DD_Support Supports directly-connected device drivers. 

Handling_Support 

Provides calls to save and restore global registers. 

Interrupt_Handling_Support 

Manages interrupt handlers. 

IO_Messages_Defs 

Defines the I/O messages mechanism interface. 

IO_Messages_Ops 

Provides driver-independent I/O message caUs for device drivers. 

Region_3_Support 

Provides a call for installing macrocode in Region 3. 
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1-2.8.2 Shared Queue Service 

Supports device drivers using the shared queues mechanism for low-speed I/O. 

Cluster_Service 

Manages cluster servers. 

IO_Shared_Queues 

Defines the shared queues I/O mechanism. 

1-2.8.3 Asynchronous Communication Service 

Defines the OS asynchronous device driver. 

As y n c_De f s Defines the asynchronous device class. 

1-2.8.4 IVIass Storage Service 

Defines the OS interface to mass storage drivers (various SCSI devices and future IPI devices). 

Bus_Independent_Disk_Def s 

Defines disk command and reply codes that are independent of any par- 
ticular I/O bus, such as SCSI or IPI. 

Bus_Independent_Streamer_Def s 

Defines command and reply codes for streaming tape drives that are inde- 
pendent of any particular I/O bus, such as SCSI or IPI. 

Bus_Independent_Tape_Def s 

Defines command and reply codes for start/stop tape drives that are inde- 
pendent of any particular I/O bus, such as SCSI or M. 

Mass_Store_Reply_Codes 

Defines I/O message reply classes and reply codes for mass storage 
devices. 

MS_Configuration_Def s 

Defines I/O message command codes and reply codes used to configure 
mass storage device. 

1-2.8.5 SCSI Service 

Defines the bus-specific interface to the SCSI bus. 

CP_SCS I_Def s Defines CP resources and data structures used to communicate with an 
SCSI mass storage I/O subsystem. 

CP_SCS l_Mgt Defines type-checking calls for SCSI buses, controllers, and devices. 

SCSI_Bus_Dependent_Defs 

Defines bus-specific commands and replies for the SCSI (Small Computer 
System Interface) I/O bus. 

1-2.8.6 Subnet Service 

Supports network-independent communication between nodes within a subnet. 

Car r ie r_Mgt Defines communication carriers and functions for manipulating carriers. 
Communication carriers are used for carrying user data, protocol data, and 
local control information. 
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Subnet_CL_AM Defines connectionless (CL) subnetwork I/O calls. For connection- 
oriented subnet calls, see the Subnet_CO_AM package. 

Subnet_CO_AM Common interface to connection-oriented (CO) subnet I/O caUs. 

Subnet_Def s Contains definitions used by other subnetwork (subnet) communication 
packages. See also the Comm_Def s and TM_Comm_Def s packages. 

Trace_Def s Contains types and definitions for tracing communications. Each com- 
munications service provider defines the procedural interface for tracing its 
own communications; for an example, see the lSO_TM_Admin package. 

Trace_Support 

Manages tracing of network communications. 

1-2.8.7 HDLC Service 

Defines the OS interface to the HDLC protocol. 
HDLC_Mgt Manages HDLC subnetworks. 

1-2.8.8 LAN Service 

Defines the OS interface to Local Area Network protocols. 

CSMA_CO_Def s Defines parameters and codes for the Intel 82588 Local Area Network 
controller. 

Et he rnet_LAN_Mgt 

Manages Ethernet subnetwoiks. 

IEEE 802 3_LAN_Mgt 

Manages IEEE 802.2/802.3 subnetworks. 
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This chapter shows you common Ada programming techniques used with system calls. (A 
future release of this manual will include a chapter on C programming techniques as well.) 
You should read this chapter before reading any subsequent chapters in this manual, because 
many examples throughout the manual depend on these concepts and techniques. 



1-3.1 Concepts 



This section introduces several concepts that are prerequisites to understanding the program- 
ming techniques presented. 

1-3.1.1 Working with Pointers 

Many system calls require or return pointers to objects managed by the OS. A pointer to an 
object is called an access descriptor (AD) and contains rights bits that control access to the 
object. An AD is defined for each OS object type. The AD is actually a BiiN™ Ada access 
type. For example, an AD for a job is defined in Job_Types: 

type job_AD is access job_object; 

By convention, access types that consist of ADs to a particular type of system object are named 
with the suffix _AD . 

Only the OS can access the internals, or representation, of objects managed by the OS. Your 
application can only perform those operations allowed by the system calls defined for a par- 
ticular object type. 

Another type of pointer, besides an AD, is a virtual address. Some system caUs require that the 
caller supply the virtual address of a buffer or record to be used by the call. Such parameters 
may have the type System, address. 

A virtual address represents an AD to an object and a 32-bit byte offset within the object. By 
convention, access types or parameters that are virtual addresses are named with the suffix 
_VA . For example, in the package Record_AM: 

type operation_status_VA is 

access operation_status_record; 
— Virtual address of an operation status record, 
pragma access_kind(operation_status_VA, virtual); 

1-3.1.2 Common Types in the System and System_Def s Packages 

The built-in BiiN™ Ada System package and the System_Def s support package define 
types used for many different system calls. In the System package: 

• System . untyped_word is the type used to represent any 32-bit quantity. It may be a 
data value, or more typically an AD to any object. 

• S y s t em . addr e s s is the type used to contain any virtual address. 

• System.subprogr am_t yp e is the type used to contain a pointer to a procedure or 
function. 

• System. null_word, System. null_address, and 

System . null_subpr ogram are the null values for the preceding three types. 

• System, ordinal, System. short_ordinal, and System.byte_ordinal are 
32-bit, 16-bit, and 8-bit unsigned integer types respectively. AU integer operators are sup- 
ported for these types, but without overflow checking. 
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In the System_Def s package: 

• System_Def s . text is the type used as a container for strings passed to and fix)m sys- 
tem calls. Sy stem_Def s . null_text is a zero-length text. 

• System_Def s . system_time_units is the type used by the OS to measure times and 
durations. 

1-3.1.3 Standard System Exceptions 

The System_Exceptions support package defines exceptions commonly encountered 
when making system calls. You should read and understand the exception descriptions in 

TM 

Sy St em_Except ions in the BUN /OS Reference Manual. 

1-3.1 .4 Package-level and Subprogram-level Variables 

Variables can be declared as either package-level or subprogram-level variables. 

A package-level variable is declared inside a package, but outside any subprogram. A 
subprogram-level variable is declared within a procedure or function. 

The lifetime of package-level variables is independent of the invocation of any subprogram 
inside the package. If the code is shared by multiple processes, these variables are visible to aU 
processes. On the other hand, subprogram-level variables exist only for the duration of the 
particular subprogram call. 

It is recommended that you avoid package-level variables for cases where multiple processes 
will access the code. Using such variables without careful synchronization between processes 
can corrupt the variables. 

1-3.2 Techniques 

This section shows you how to: 

• Use unchecked type conversion 

• Use overlays as an alternative to unchecked type conversion 

• Import operators 

• Allocate a buffer 

• Recover from record overflow 

• Handle recoverable exceptions 

• Use paired caUs. 

All techniques are illustrated with excerpts from compiled examples. Appendix X-A contains 
complete listings for aU examples. 

1-3.2.1 Using Unchecked Type Conversion 

TM 

In different contexts, the OS may require different BiiN Ada types to be used for the same 
value. If these BiiN™ Ada types are not compatible according to BiiN™ Ada's type conversion 
rules, then an unchecked conversion between types is required. 
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Declarations Used: Unchecked_conversion 

BiiN™ Ada generic function that does compile-time conversion between 
otherwise incompatible types. 



For example, the BiiN Ada type used to contain any AD is System . untyped word. 
Some system calls that can operate on any AD use untyped_word as the BiiN Ada type of 
their parameters or their returned value. Unchecked conversion can convert between other AD 
types and untyped_word. 

To convert between two types with unchecked conversion: 

TM 

1. The BiiN Ada Unchecked_conver sion imit must be in your unit's with clause. 

2. Your program must instantiate Unchecked_conver s ion to create a new type conver- 
sion function. 

3. Your program uses the new type conversion function to do the conversion. 

In the following example, which changes the current directory in a caller's process globals, the 
value needs to be converted from type directory_AD to type untyped_word. These 
steps are shown in the following excerpts from the List_current_directory_cmd_ex 
example: 

with Byte_Stream AM, 



1 

9 

11 

37 



Unchecked_Conversion; 
procedure List_current_directory_cmd_ex 
is 



41 function Direct ory_AD_from_untyped_word is 

42 new Unchecked_conversion ( 

43 source => System. untyped_word, 

44 target => Directory_Mgt .directory_AD) ; 

79 begin 

92 — Open directory for reading, filtered by 

93 — ": pattern": 
94 

95 opened_dir := Directory_Mgt .Open_directory { 

96 dir => Directory_AD_f rom_untyped_word ( 

97 Process_Mgt .Get_process_globals_entry { 

98 Process_Mgt_Types .current_dir) ) , 

99 pattern => pattern) ; 

12 6 end List_current_directory_cmd_ex; 

Line 9 includes Unchecked_conversion in the unit's with clause. 

Lines 44-47 create the Untyped_word_f rom_directory function. The function created 
by specifying Unchecked_conver sion accepts one parameter, of the source type, and 
returns a result of the target type. 

Line 96 shows a call to the new function, required because Process_Mgt 
. Get__process_globals_entry uses the untyped_word type for the value returned, 
while Directory_Mgt . Open_directory requires a value of type directory_AD. 
Such calls are evaluated at compile-time and have no run-time cost. 
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1-3.2.2 Using Overlays as an Alternative to Unchecked Type Conversion 



rTM 



BiiN Ada provides an overlay feature that allows a programmer to specify the memory ad- 
dress of a variable, rather than relying on the compiler to allocate storage and determine the 
variable's address. A variable can be given the same address as a previously declared 
parameter or variable, providing different BiiN™ Ada types for the same value. The different 
names can be used as an alternative to performing unchecked type conversions where different 
BiiN™ Ada types are needed. 



CAUTION 



Overlays can be dangerous if used in an unstructured maimer because this technique 
voids all of the strong typing of BiiN™ Ada. Serious programming errors can result. 

This excerpt is from the Show_current_directory_cmd_ex example: 

10 procedure Show_current_directory_cmd_ex 
29 is 

37 current_dir: Directory_Mgt .directory_AD := 

38 Directory_Mgt .directory_AD ( 

39 Process_Mgt .Get_process_globals_entry ( 

40 Process_Mgt_Types.current_dir) ) ; 

41 — Current directory's AD. 

4 3 current_dir_untyped : System. untyped_word; 

4 4 FOR current_dir_untyped USE AT 

45 current_dir' address; 

4 6 — Current directory's AD as an untyped word. 

51 begin 

52 

53 — Get current directory's pathname: 

54 

55 Directory_Mgt .Get_name ( 

56 obj => current_dir_untyped, 

57 name => dir_name) ; 

73 end Show_current_directory_cmd_ex; 

Lines 43 — 45 show how an overlay with a different type is declared. The local variables 
current_dir and curr ent_dir_untyped name the same word in memory, but with 
different types. The name current_dir is used wherever the type 
Directory_Mgt . directory_AD is required. The name current_dir_untyped is 
used wherever the type System. untyped_word is required. 

Line 56 shows dir_untyped used in the call to Directory_Mgt . Get_name. 

1-3.2.3 Importing Operators 

Some BiiN™ Ada operators ("=","+", and so on) are defined for many types declared in 
System Services packages or the BiiN™ Ada System package. The following rules indicate 
where operators are defined: 

1. The package that defines an access type also defines "=" and "/=" for that type. 

2. The package that defines an enumeration type also defines all relational operators for that 
type. If a subtype of the enumeration type is declared in another package, the subtype still 
uses the operators defined in the first package for the base enumeration type. 
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3. The package that defines a record type also defines "=" and "/=" for that type. 

4. The System package defines for all ordinal types all operators allowed for integers. 

5. The Long_Integer_Def s package defines for long integers all operators allowed for ^ 
integers. 

6. The Text_Mgt package defines the operators "<", "<=", ">", and ">=" for the 
System_Def s . text record type. The System_Def s package implicitly defines "=" 
and "/=" for texts. 

7. Other OS packages may define additional operators for their types. 

Your program can use such operators in two ways: 

1. Explicitly qualify each use with the package name. 

2. Import the package that defines the operators with a use clause, and then use the operators 
normally. 

In either case, the packages must be listed in your program's with clause. 

If A, B, and C are long integer variables, the following code fragments show how to write A 
: = B + C ; using the two techniques. First, using explicit qualification: 

A := Long_Integer_Defs."+" (B, C) ; 

TM 

Note that BiiN Ada syntax requires that a qualified operator be quoted and does not allow an 
operator qualified with a package name to be used as an infix operator. The following code is 
WRONG: 

A := B Long_Integer_Defs. "+" C; 

The next code fragment shows importing Long_Integer_Def s with a use clavise and then 
doing the computation: 

use Long_Integer_Defs; 
A := B + C; 

Recommended coding practice is to import packages if operators fix)m the package must be 
used, with these restrictions: 

1. References to any other calls or declarations in the package should still be fully qualified. 
For example, write Long_Integer_Def s . zero instead of just zero . 

2. If operators from a particular package are used only in a particular call or code block, then 
usq the same scope for the use clause. 

use clauses should be used only where necessary. If names of entities declared in other 
packages are not fuUy qualified with their package names, then your program is harder to 
understand and harder to maintain. 



1=3.2.4 Allocating a Buffer 



When you need to set up a buffer to process the results of a system call, there are two main 
options: 

Allocate a buffer as a local variable. 

This is the recommended option, because allocation is fast and the buffer 
can be reclaimed as soon as control exits the subprogram or block. 
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Create an object for the buffer. 

This is useful when the buffer may need to be resized, as it might be when 
reading variable-length records. A disadvantage is the overhead required 
to allocate and deallocate an object 

The following excerpt from the example List_current_directory_cmd_ex shows 
how to allocate a buffer as a local variable. In this example, the buffer holds each entry name 
between reading it and writing it. 

11 procedure List_current_directory_cmd_ex 
37 is 

70 name_buf f er : array {1 .. 250) of character; 

71 — Each entry name is read into this buffer 

72 — and then written from it. 

7 9 begin 

102 — Get and write each entry name: 

103 

104 loop 

105 

106 length := Byte_St ream_AM. Ops. Read { 

107 opened_dev => opened_dir, 

108 buffer_VA => name_buffer' address, 

109 length => name_buffer' size/8) ; 
110 

111 Byte_Stream_AM.Ops.Write{ 

112 opened_dev => standard_output, 

113 buffer_VA => name_buffer' address, 

114 length => length) ; 
115 

116 end loop; 

12 6 end List_current_directory_cmd_ex; 

See Output_r ecords_ex in Appendix X-A for an example of a dynamically sized buffer 
contained in a separate object. 

1-3.2.5 Recovering from Record Overflow 

Some system calls assign array values to fixed-length records supplied by callers as out 
parameters. If an array value is too large, these system calls simply assign all the values that 
will fit in the record and assign the total array's length to a field in the record. 

Checking for such "record overflows" is the caller's responsibility. Any system call that as- 
signs a text record behaves in this way; record overflow assigns an invalid text with length > 
max_length. "Information" calls that return lists of processes in a job, jobs in a session, 
entries in an authority list, or other varying-length arrays can overflow in the same way. 

The following excerpt from the Stored_Account_Mgt_ex example package body shows 
how an application checks for text record overflow and retries if necessary. The same tech- 
nique can be used to handle similar overflows for other record types. 

The text record is declared and used in a nested block. To retry, the variable controlling the 
text's size is increased and control jumps back to the beginning of the block, reentering the 
block and reallocating the text with the new size. Because the text record is declared in a 
nested block, it can only be used within that block. 
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552 procedure Destroy_account ( 

594 is 

602 begin '" ,- r 

607 loop 

614 path_length: integer := 60; 

615 — Initial text length for name assigned 

616 — by "Directory_Mgt .Get_name". If 

617 — insufficient, then the value is 

618 — increased and the operation is 

619 — repeated. 

629 loop 

630 declare 

631 path_text : System_Defs.text (path_length) ; 

632 begin 

633 Directory_Mgt .Get_name ( 

634 obj => account_untyped, 

635 name => path_text); — out. 

636 if path_text. length > 

637 path_text .max_length then 

638 • — Text was lost. Retry: 

639 path_length := path_text. length; 

640 else 

641 Directory_Mgt .Delete (path_text) ; 

642 EXIT; 
643 

64 4 end if; 

64 5 exception 

64 6 when Directory_Mgt .no_name => 

647 EXIT; 

648 

64 9 end; 

650 end loop; • 

668 EXIT; 

669 end loop; 

671 end Destroy_account; 

1-3.2.6 Handling Recoverable Exceptions 

Most exceptions raised by system calls cannot be recovered from. When an exception can be 
recovered from, this section describes a specific coding technique for recovery. 

If an exception occurs, execution of the surrounding block is abandoned and any exception 
handler is entered. An exception handler cannot jump back into the abandoned code to retry an 
operation. Thus, if an operation needs to be retried in some cases, then the operation should be 
placed in a nested block within a loop. The nested block can then handle the possible cases: 

• The operation is successful. In this case, a return or exit statement can exit the loop. 

• The operation is not successful and a recoverable exception is raised. In this case, the 
nested block contains a handler for the exception. After handling the exception, control 
loops back and the operation can be retried. 

• The operation is not successful and a non-recoverable exception is raised. In this case, 
the exception is simply propagated. 

Using a nested block to retry an operation and handle a recoverable exception is illustrated by 
the following excerpt from the Stored_Account_Mgt example package body: 
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405 loop 

406 if Transaction_Mgt .Get_default_transaction = 

407 null then 

408 Transaction_Mgt .Start_transaction; 

409 trans := true; 

410 end if; 

411 begin 

419 Passive_Store_Mgt .Update (account_untyped) 

420 if trans then 

421 Transaction_Mgt .Commit_transaction; 

422 end if; 

423 RETURN account_rep, balance; 

426 exception 

427 when System_Exceptions. 

428 transaction_timestamp_conf lict => 

429 if trans then 

430 Transaction_Mgt .Abort_transaction; 

431 else 

432 RAISE; 
433 

434 end if; 

435 when others => 

436 if trans then 

437 Transaction_Mgt .Abort_transaction; 

438 end if; 

439 RAISE; 
44 end; 

441 end loop; 



1-3.2.7 Using Paired Calls 



Some important system calls must be carefully paired for your application to woric properly. 
Some common pairings are: 

• In Semaphore_Mgt: P (Lock) with V (Unlock). 

• In Transaction_Mgt: Start_transaction with either of 
Cominit_transaction (if successftil) or Abort_transaction (if unsuccessful). 

• In each I/O access method package: Open with Close. If Clo se is omitted, an opened 
device is closed when all jobs using it terminate. 

Pairing system calls is complicated by exceptions, which can cause unexpected transfers of 
control out of a code block. If a matching system call must be executed before leaving a block, 
use a when others exception handler, as in the following excerpt from the 
Synnbol_Table_Ex example: 

127 begin 

128 Semaphore_Mgt .P (symbol_table . lock) ; 

151 exception 

152 when others => 

153 Semaphore_Mgt .V(symbol_table. lock) ; 

154 RAISE; 

155 — Reraise exception that entered handler. 

156 end; 
157 

158 Semaphore Mgt .V (symbol table. lock); 
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1-3.3 Summary 

• Many system calls require or return pointers to objects managed by the OS. 

• A pointer to an object is called an access descriptor (AD) and contains rights bits that 
control access to the object. 

• By convention, access types that consist of ADs to a particular type of object are named 
with the suffix _AD . 

• By convention, access types or parameters that are virtual addresses are named with the 
suffix _VA . 

• The built-in BiiN™ Ada S y s t em package and the S y s t em_De f s support package define 
types used for many different system calls. 

• The System_Exceptions support package defines exceptions commonly encountered 
when making system caUs. 
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Part II 

Support Services 



This part of the BUN™ /OS Guide shows you how to use Support Services, needed throughout 
all otiier service areas for basic tasks. The chapters in this part are: 

Using Utility Packages 

Gives data structures and examples for common system types and opera- 
tions. 

Using Objects and ADs 

Shows basic techniques for using objects and ADs. 

Storing Objects Shows how to use the system's distributed storage system to store objects 
on disk. 

Starting and Resolving Transactions 

Shows how to use transactions to group operations so that either all opera- 
tions in the group succeed or all are rolled back. 

Writing Messages Shows how to use the system's facilities for writing messages. The mes- 
sage service allows messages to be expressed in different languages and 
edited without access to source code. 

Support Services contains the following services and packages: 

utility service : 

Long_Integer_Defs 

Machine_Code_Insert ion 

String_List_Mgt 

System 

System_Defs 

System_Exceptions 

Text_Mgt 

object service : 

Access_Mgt 
Attribute_Mgt 
Object_Mgt 
Passive_Store_Mgt 

transaction service : 

Transact ion_Mgt 

message service : 

History_Ser vices 

Incident_Defs 

Message_Adm 

Message_Ser vices 

Message_Stack_Mgt 

Msg_Ob j ect_De f s 

System_Error_Recording 
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Utility packages are used throughout the system by services in all the services areas. Many 
system calls require parameters of the types in these packages, such as text, string list, 
and long integer. This chapter shows how to perform common operations using these 
types. 

Packages Used: 

String_List_Mgt 

Provides operations on string lists. 

Text_Mgt Provides operations on text records. 

Long_Integer_Def s 

Defines types and calls for 64-bit long integers. 

Sy st em_Def s Provides common definitions used throughout the OS. 



Figure II- 1-1 shows the data structures for the objects discussed in this chapter. 
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11-1.1,1 string Lists 



A string list is a standard container for a list of strings. String lists are often used with text 
records. 
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String lists have the System_Def s . string_list type. A particular string list has a fixed 
size and can contain any string values that will fit. An individual string in a string list is 
preceded by a two-byte length field and can have fi^om to 32,767 characters. 

A string hst contains these fields: 

max_length A discriminant, specifying the maximum number of bytes that the list 
field can hold. 

length The number of bytes used in the li st field. 

count The number of strings in the string list. 

list An array of max_l e n gt h characters, indexed from 1 to ma x_l e ngt h . 

li St ( 1 . . length ) contains the strings in the list. Each string is contained in a record of 
type System_Def s . var_text, a two-byte length followed by the specified number of 
characters. Successive strings are packed with no unused bytes and no alignment require- 
ments. 

list (length + 1 .. max_length) is the fiiee space available in the string list. 

System calls that retrieve string lists do so via out parameters. If a string list is larger than the 
space in a particular string list record, then such calls assign the actual length of the string list 
to the length field, the actual number of strings to the count field, and the strings that will 
actually fit (without breaking in mid-string) to the list field. This sort of overflowing string 
hst is an invalid string list. It is the application's responsibility to check for invalid string lists 
where they can occur. 

See also String_List_Mgt. 

11-1.1.2 Texts 

A text is the standard container for a string. 

Texts have the Sy stem_Def s .text type. A particular text can hold a fixed-size string and 
contains a value of any length up to that size. Text sizes range from to 32,767 characters. 

A text contains these fields: 

max_length A discriminant, specifying the maximum number of characters that the text 
can hold. 

length Number of characters actually used, or if greater than max_lengt h, the 

number of characters needed in the text. 

value An array of max_length characters, indexed from 1 to max_length. 

Many system calls assign strings to text out parameters. If the string is larger than the space 
in the text (overflow), such calls assign the actual size of the string to the length field and 
assign the first max_length characters of the string to the value field. Such a text value, 
with length > max_length, is an invalid text. 

See Chapter 1-3 for a technique to recover from such a text overflow. 

See also Text_Mgt. 
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11-1.1.3 Long Integers 

A long integer is represented as a record of two ordinals. 

Long integers are of type Long_Integer_Def s . long_integer and range from 
-(2**63) to (2**63)-l. 

The range of long integers in decimal is: 

-9,223,372,036,854,775,808 .. 9,223,372,036,854,775,807 

Note that the record's representation reverses the order of the h and 1 fields, so that the low 
word is first in memory followed by the high word. This representation is consistent with the 
representation used for all other multi-byte integer and ordinal types: the least significant byte 
is at the lowest memory address, followed by the next most significant byte, etc. The most 
significant byte is always at the highest memory address used. 

See also Long_Integer_Def s. 

11-1 .2 Techniques 

After reading this section, you wiU be able to: 

Use a hteral text 

Declare a constant text 

Call a procedure with a text result 

Create a string list 

Read elements from a string list 

Use a literal long integer 

Compute with long integers 

Convert between strings and long integers. 

Complete listings of the programs used in the following examples can be found in Appendix 
X-A. 

11-1.2.1 Using a Literal Text 

The following example fi"om the inventory example program (module 
Inventory_Messages) shows the use of a literal text: 

24 message_f ile: constant System_Defs .text_AD := 

25 new System_Defs .text' { 

26 31,31, "/example/inventory/message_f ile") ; 

27 — AD to message file text name. 

11-1.2.2 Declaring a Constant Text 

The following example from the inventory example program (module 
I n ve nt o r y Repo r t s) shows the declaration of a constant text: 
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5 5 report_by_part_DDef_str : constant string := 

56 "/example/inventory/DDefs/report_by_part"; 

57 — String constant for "report by part" 

58 — report DDef ' s pathname. 
59 

60 report_by_jpart_DDef_pathname : 

61 System_Defs .text ( 

62 report_by_part_DDef_str' length) := ( 

63 report_by_part_DDef_str' length, 

64 report_by_part_DDef_str' length, 

65 report_by_part_DDef_str) ; 

66 — Text constant from "report by part" 

67 — DDef's pathname string. 

11-1.2.3 Calling a Procedure with a Text Result 

After calling a procedure that retrieves a text result, be sure to check for an invalid text (not 
enough space to accommodate the desired text). There are many system calls that return a 
result of type text; Directory_Mgt . Get_name is just one. 

Calls Used: 

Directory_Mgt . Get_name 

Gets the fuU pathname of an object's master AD. 

The following example is from the Stored_Account_Mgt_Ex example package body in 
Appendix X-A. 



629 


loop 


630 


declare 


631 


path_text : System_Def s . text (path_ 


632 


begin 


633 


Directory_Mgt . Get_name ( 


634 


obj => account_untyped. 


635 


name => path text); — out. 


63 6 


if path_text . length > 


637 


path text .max_length then 


638 


— Text was lost. Retry: 


63 9 


path_length := path_text. length; 


640 


else 


641 


Directory Mgt .Delete (path text); 


642 


EXIT; 


64 3 




644 


end if; 


645 


exception 


64 6 


when Directory Mgt.no name => 


647 


EXIT; 


648 




649 


end; 


650 


end loop; 



In the above example, note how the developer enclosed the caU within a nested block to check 
if all the characters in the desired text actually fit into the destination text. 

The parameter to receive the text is called path_t ext. After the pathname is received from 
Directory_Mgt . Get_name, the values path_text . length and 
path_t ext . max_length are compared to see if the number of bytes in the text was 
greater than the maximum specified for the text. If so, then the text is resized to the higher size 
and Directory_Mgt . Get_name is repeated. 
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11-1.2.4 Creating a String List 

The simplest way to create a string list is to use String_List_Mgt and build the string list 
from texts. 

Calls Used: 

String_List_Mgt . Set 

Copies a text to a string list 

String_List_Mgt . Append 

Appends a text to a string list. 



The following example shows how to create a string list 

1 with String_List_Mgt, 

2 System_Defs; 
3 

4 procedure String_list_ex 
5 

6 — Function: 

7 — Create string list with following entries: 

8 — 1. "ux_group" 

9 — 2. "world" 

10 is 

11 string_list: System_Defs.string_list (255) ; 

12 begin 
13 

14 — 1) "ux_group" 

15 String_List_Mgt . Set {string_list , 

16 System_Defs.text' (8, 8, "ux_group") ) ; 
17 

18 — 2) "world" 

19 String_List_Mgt .Append (string_list, 

20 System_Defs.text' (5, 5, "world")); 
21 

22 end String_list_ex; 

li-1.2.5 Reading Elements from a String List 

The package String_List_Mgt provides calls to access the strings in a string list. 

Get_element retrieves a string from a string list, given its position number. 

Get_element_by_index retrieves a string from a string list given an index variable, 
which it updates. Both can be used to loop through all strings in a string list Get_element 
is simpler to use. Get_element_by_index executes more quickly, especially for large 
string lists. 

Locate finds a string and returns its position number. 

Locate_index finds a string and returns its index. 

Calls Used: 

String_List_Mgt . Get_element_by_index 

Gets the string with a specified index from a string list, and updates the 
index variable to reference the next string. 
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The following excerpt from the Create_nanie_space_cmd_ex example shows how 
Get_element_by_index can loop through all strings in a string list: 

156 i := 1; 

157 

158 loop 

159 

160 String_List_Mgt .Get_element_by_index { 

161 from => directory_list, 

162 list_index => i, 

163 element => directoryj>ath) ; 
164 

165 — Exit after last string: 

166 

167 EXIT when i = 0; 

203 end loop; 

11-1.2.6 Using a Literal Long Integer 

The following example from the Long_Integer_Ex example package shows the use of a 
literal long integer: 

24 4 — Declaring a negative long integer constant, 

24 5 — the easy way and the hard way: 

246 

24 7 negative_twenty : constant long_integer := 

248 - long_integer' (0, 20); 

249 

250 another_negative_twenty : constant long_integer := 

251 (16#ffff_ffff#, 16#ffff_ffec#); 

252 — Use the hard way when you want a declaration 

253 — elaborated at compile-time instead of 

254 — at run-time. 

11-1.2.7 Computing with Long Integers 

All standard Ada arithmetic and relational operators are defined for long integers. The = and 
/= operators are implemented using Ada record comparison. All other long integer operators 
are defined in the package Long_Integer_Def s. 

To use long integer operators, a program unit must explicitly use Long_Integer_Def s. 

Long integers do not support Ada attributes of integers. A long integer is a record type, hence 
the usual Ada attributes defined for integers cannot be applied. The following list gives long 
integer alternatives to Ada attributes of integers: 

' first Use Long_Integer_Def s .min_int. 

'last UseLong_Integer_Defs .max_int. 

'width At most 20 characters are required to represent a long integer as a string. 

Long_lnteger_Def s uses 31 characters, which allows ample space for 
embedded underscores. 

' po s Not needed; x ' po s = x for integer types. 

' val Not needed; x' val = x for integer types. 

'succ Add one. 

' p r e d Subtract one. 

' image CaU Long_Integer_Def s . Long_integer_image. 
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' value Call Long_Integer_Def s . Long_integer_value. 

11-1.2.8 Converting Between Strings and Long Integers 

To convert between a string type and a long integer type, Long_Integer_Def s provides 
two straightforward calls: 

Calls Used: 

Long_Integer_Def s . Long_integer_image 

Converts a long integer to a string image. 

Long_Integer_Def s . Long_integer_value 

Converts a string image to a long integer. 



See the Long_integer_value function in the Long_Integer_Ex package in Appendix 
X-A for an example of code that converts a string image to a long integer. (The code is too 
long to include here.) 

11-1.2.9 Summary 

• Many system calls require parameters of the types text, string list, and long 
integer. 

• A text is the standard container for a string. 

• A string list is a standard container for a hst of strings. 

• A long integer is represented as a record of two ordinals. AU standard Ada arithmetic and 
relational operators are defined for long integers. 
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11-2.1 Concepts 



This chapter presents an overview of objects and access descriptors. Objects are the fun- 
damental units of object-oriented programming. Access deseriptors are pointers tiiat reference 
these objects. 



Packages Used: 

Access_Mgt 
Object Mgt 



Interface for checking or changing rights in access descriptors. 

Provides basic calls for object allocation, typing, and storage management. 
Defines access rights in ADs. 



Access Descriptor 






Pointer 


Rights 








Object 













Figure n-2-1. AD and Object 



11-2.1.1 What is an Object? 



An object is a typed and protected memory segment. An object has the following charac- 
teristics: 

A unique identity that cannot be forged, and is guaranteed to exist 
as long as references to the object exist 

A type, determined by a Type Definition Object (TDO) 

A representation, an area of active memory or passive store that 
holds the object's contents 

A Storage Resource Object (SRO) from which the object is 
allocated and to which its memory space is returned when deallocated 

A lifetime that determines whether an object's existence is 

limited to the lifetime of a single job or is 

indefinite 

A memory type that determines whether the object will reside in 
normal (swappable) memory or frozen (non-swappable) memory. 
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The size of an object may be from to liP- bytes, and can be dynamically changed. Up to i?-^ 
objects are possible in a node's four gigabytes of active memory. 

A type manager is a routine that provides basic operations for aU objects of its type. A TDO 
defines a type manager's type. Object types are specified when objects are created, and cannot 
be changed. 

Only a type manager can create objects of its type, or read or write to the object representation. 
Other services can reference objects of a type manager's type, but must call the type manager 
to read or change the objects. Therefore, the integrity of type-managed objects depends only 
on the type manager, and not on other services that use the object. 

11-2.1 .2 What is an Access Descriptor? 

An access descriptor is a protected pointer to an object, with rights describing how ti^e object 
can be used. Figure II-2-2 shows an access descriptor layout. 



Word 
Boundary 



Tag 



1 6 5 4 3 2 10 


Object Index (26 bits) | 

























Read Rep R 
Write Rep R 
Use Right 
Modify Righ 
Control Righ 
Local 



ights ^ 

ights J 

' \ 

3hts > 

iqhts J 



Rep Rights 
Type Rights 



Figure 11-2-2. A Valid Access Descriptor 



An AD is represented by a memory word with Ada type System . untyped_word. An 
untyped_word is a one-word, word-aligned value corresponding to one 33-bit memory 
word, 32 bits of information and a tag bit. (The tag bit indicates whether the word is a valid 
AD.) An untyped word can be interpreted as either an access descriptor word or as a non-AD 
word. 

If interpreted as an AD, an untyped_word contains: 

• A valid AD that references an object and provides rights to the object when the tag bit is 1 

• A null AD when the tag bit is 0, regardless of the value of the first 32 bits. 

If interpreted as a non-AD, an untyped_word contains 32 bits of data and the tag bit is 
ignored. 

By convention, access descriptor names end with _AD. For example, direct ory_AD is an 
access descriptor that references a directory object. 
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An AD contains five rights bits: two representation rights and three type rights. These rights 
are described in the following sections. 

11-2.1.3 Rep Rights Control Access to an Object's Representation 

Representation rights are required to read or write the object's representation. These rights 
grant access to an object's physical layout in memory. Rep rights are checked by the CPU 
whenever a program reads or writes memory. If needed rep rights are not present, then 
System_Exceptions . insuf f icient_rep_right s is raised. If an object has a type 
manager, then the type manager normally removes rep rights on any ADs it exports for the 
object. A type manager can turn on ("amplify") rep rights on ADs for objects that it manages. 

il-2.1.4 Type Rights Control What Type-Specific Operations are Allowed 

Type rights are specific to the object type and provide access to an object's logical structure by 
determining what type manager calls are allowed on that object. The three rights are desig- 
nated use, modify and control by convention to ensure that tiiey are interpreted consistently 
regardless of object type. 

Use - To get information about the object 

Modify - To change the contents of an object but retain its existence and representation 

Control - To destroy the object, or perform other privileged operations. 

Use and modify rights correspond to read and write rights for files. Control rights give the 
user maximum control over the object. The actual functions of these rights is determined by 
the type manager. Usually, these types are renamed to reflect the particular usage of the rights. 
For example, the naming service defines list and store rights for directories, which correspond 
to use and modify rights. 

These rights do not form a hierarchy in that a type manager may provide any one or more of 
them. For example, a type manager could interpret modify rights and not interpret use or 
control rights, rights. 

Checking and enforcing type rights is done by type managers and not by the CPU. A type 
manager raises System_Exceptions . insuf ficient_type_rights if needed type 
rights are missing. 

11-2.1 .5 Generic Objects 

When an object is created without specifying a particular TDO, the new object is generic and is 
associated with the generic TDO. A generic object is used only as a memory segment. It does 
not have a type manager, and has the same TDO as all other generic objects. The generic TDO 

TM 

IS held by the BiiN Operating System. Applications can create and manage generic objects. 

11-2.1.6 Building Type l\/lanagers That Define New Object Types 

Type managers can be built to support new object types. A new type is defined by creating a 
new TDO. See Chapter VII-3 for instructions for building a type manager for a new type. 



II-2-4 Using Objects and ADs 



PRELIMINARY 

11-2.2 Techniques 

After reading this section, you will be able to: 

• Check an object's type 

• Check rights on an AD 

• Remove rights from an AD 

• Create a generic object 

• Resize an object 

• Get an object's size 

• Deallocate an object. 

11-2.2.1 Checking an Object's Type 

An application can check that an object is of a particular type before attempting to perfomi 
type-specific operations on it Each BiiN Operating System type manager provides an I s_ 
call that checks whether an AD points to an object of the managed type. The following code is 
from the Process_Globals_Support_Ex example. After the process global entry for 
the home directory is retrieved, the following code checks to verify that it is a directory object. 

323 if not Directory_Mgt . Is_directory (dir_untyped) then 

324 RAISE System_Exceptions . type_mismatch; 

11-2.2.2 Checking Rights on an AD 

The access rights of an AD can be examined. The rights to be checked for are set in 

Ob ject_Mgt . right s_mask. Then Access_Mgt . Permits is called. True is returned 

if the AD has the rights which were set in the mask. 

11-2.2.3 Removing Rights From an AD 

The access rights of an AD can be removed. The rights to be removed are set in a rights mask. 
Then Access_Mgt . Remove is called. An AD to the same object is returned without the 
rights set in the mask. The following code is from the Account_Mgt_Ex example. While 
creating a new account, all rep rights are removed from the returned AD thus requiring all 
reading and writing of the account object to be performed via the account type manager. 

110 account_untyped := Access_Mgt .Remove ( 

111 AD => account_untyped, 

112 rights => Object_Mgt .read_write_rights) ; 

ii-2.2.4 Creating a Generic Object 

A new object can be allocated with Ob ject_Mgt . Allocate. If no TDO is specified in the 
call, the new object is generic. Another method for creating objects is to use the Ada new 
allocator. The following example allocates a symbol table object with space for 
table_size entries and no entries in use. 

223 symbol_table := new syrnbol_table_ob ject ( 

224 table_size) ; 

225 symbol_table. length := 0; 

226 — Symbol table initially has space for 100 

227 — entries with in use. 
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li-2.2.5 Resizing an Object 

Ob ject_Mgt .Allocate allocates an object at a specified size. That size can be deter- 
mined with Ob ject_Mgt . Get_ob ject_size. (Object size is specified in words.) The 
size can also be changed with Ob ject_Mgt . Resize as shown in the following example: 

98 Ob ject_Mgt. Resize ( 

99 obj => symbol_table_untyped, 

100 size => 3 + (2 * symbol_table .max_length * ( 

101 symbol_entry' size/32) )) ; 
102 

103 max_length_access := 2 * symbol_table .max_length; 

In this example, a symbol table is expanded so that it will hold twice as many entries and 
changes the maximum length of a symbol table entry. 

11-2.2.6 Deallocating an Object 

Objects can be dynamically deallocated. The following excerpt from Account_Mgt_Ex 
shows an account object checked for a zero balance and then destroyed (deallocated). 

326 begin 

327 account_untyped := Ace e s s_Mgt . Import ( 

328 AD => account_untyped, 

329 rights => destroy_rights, 

330 tdo => account_TDO) ; 
331 

332 if account_rep. balance /= Long_Integer_Defs.zero then 

333 RAISE balance_not_zero; 
334 

335 else 

336 Ob ject_Mgt .Deallocate (account_untyped) ; 
337 

338 end if; 



11-2.3 Summary 

• An object is a typed and protected memory segment. 

• An access descriptor is a protected pointer to an object, with rights describing how the 
pointer can be used. 

• An object's representation is an area of active memory or passive store that holds the 
object's contents. 

• A type manager is a routine that provides basic operations for all objects of its type. 

• A TDO defines a type manager's type. 

• Type rights are specific to the object type and provide access to an object's logical structure 
by determining what type manager calls are allowed on that object. 

• Representation rights are required to read or write the object's representation. 

• A generic object is used only as a memory segment. It does not have a type manager, and 
has the same TDO as all other generic objects. 
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Passive store is the collection of objects stored on disk in a BiiN™ system. This chapter shows 
you how to store objects on disk. 

Packages Used: 

Directory_Mgt Manages directories and directory entries. 

Passive_Store_Mgt 

Provides a distributed object filing system. 



Passive store is distributed-spread over multiple nodes and transparently accessible from any 
node (Figure II-3-1). Of course passive store is equally usable on a single-node system. 




Figure n-3-1. Passive Store is a Distributed Object Filing Service that 
Unifies all Nodes in a BiiN™ System. 



Passive store is reliable-stored objects survive system crashes and changes to stored objects 
are transaction-oriented. 

TM 

In many ways passive store is the "glue" that holds together a distributed BiiN system. Many 
system objects are stored there, such as files, directories, programs, and TDOs. 

The use of passive store is typically hidden by the services that use it. For example, the filing 
service and directory service handle all needed passive store operations for files and direc- 
tories. 
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11-3.1 Concepts 

11-3.1.1 Comparing Passive Store, Files, and Directories 

All objects stored on disk are "in" passive store, including file objects and directory objects. 
However, an application that only uses files and directories can ignore most aspects of passive 
store and use files aiid directories in a familiar way. Even for an application that uses other 
object types, files and directories can be appropriate containers for much of the application's 
stored data. The application designer should consider these points: 

• Files support byte stream I/O and record I/O. Several record-structured file organizations 
are supported and a rich set of file management, file indexing, and record access operations 
is provided. 

• Files cannot contain ADs. 

• Directories can contain ADs but have a fixed structure: a set of <name, AD> pairs, such 
that each name is unique within its directory. 

• If the application wants to store its own typed objects on disk, objects that can contain ADs 
and have an arbitrary structure, then it must use passive store directly to store those objects. 

11-3.1.2 Using Passive Store at Different Levels 

Passive store can be used at three different levels: 

1. At the conventional application level, an application can use files and directories. Passive 
store is transparent, but the application may still benefit from the distributed file system and 
the flexible protection model. 

2. At the sophisticated application level, an application can: 

• Request that system objects, such as TDOs or authority lists, be stored. 

• Create its own network of generic objects and store it. 

3. At the object-oriented application level, an application can defme new object types and type 
manager modules for those types. Each type manager uses the Passive_Store_Mgt 
package to customize the passive store behavior of its object type. 

Passive_Store_Mgt is directly used by the second- and third-level applications. Two 
different groups of calls are provided for the two different levels. The sophisticated applica- 
tion can use Request_ caUs, such as Request_update, which do not require any rights. 
However, an object's type manager can specify type-specific handling of such calls or refuse 
them by raising System_Exceptions . operation_not_supported. A type 
manager in an object-oriented application can use direct calls, such as Update, which require 
rep rights. A type manager only uses the direct calls for the objects that it manages. The two 
groups of caUs appear in the same package because one module will often use both groups of 
calls: the direct caUs for objects that it manages and the Request_ calls for objects that other 
modules manage. Oiapter VII-6 shows how to build a type manager for a stored object type. 

11-3.1.3 Object Versions 

Active memory is the collection of objects in virtual memory on a particular BiiN™ node. An 
object can have versions in both active memory and passive store (Figure II-3-2). 
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Figure 11-3-2. A Single Object can have Passive and Active Versions. 



An object can have multiple active versions, in use by different jobs or nodes, but can have 
only one passive version. Though the term "version" is used, passive store is not a "version 
control" or "revision control" system and cannot store or reconstruct any but the most current 
passive version. The passive store does ensure that out-of-date active versions cannot corrupt 
an object's passive version. 
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Only active versions can be directly read or written. Reading or writing a stored object with no 
active version causes activation of the object, creation of an active version that is then read or 
written. 

Objects are activated when needed in the same way that pages of virtual memory are swapped 
in when needed. Both operations are invisible to your application. 

Changing an object's active version does not change the passive version. 

An active version of an object can only be created from the object's passive version. There is 
no way to create an active version from another active version. 

Local objects are activated on a per-job basis. If jobs A and B both use an object, then they get 
separate active versions. Activating a local object consumes storage in the job's local SRO 
(storage resource object). 

Global objects are activated on a per-node basis. If jobs A and B both use an object and are on 
the same node, then they share an active version. If jobs A and B are on different nodes, then 
they use different active versions. A global object is activated in either the normal or frozen 
global SRO, depending on its memory type. 
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11-3.1 .5 Activation as Reincarnation 

A passive object can "live" multiple times, in the form of successive activations in different 
jobs. For example, job A may create and passivate an object, and then tenninate. Some time 
later, job B references the object and a second active version is created, a second active "life" 
for the object. Whether an object remembers its "past lives" depends on whether or not each 
job passivates any changes that it makes. 

[1-3.1 .6 AD Activation 

Activating an object activates all ADs in the object. However, activating an object does not 
activate the objects that it references. For example, a program accesses object A, triggering 
A's activation. A contains an AD for object B. The AD for B is activated, but not B itself. B 
will subsequently be activated if the program accesses it. 

AD activation is the point at which protection of passive objects is implemented. Chapter III-3 
describes how passive objects are protected. When an AD is activated as part of object activa- 
tion, then a null AD is activated in its place if the owner of the object that contains the AD is 
not allowed access to the object referenced by the AD. 

ADs are frequently activated by being retrieved from directory entries. Protection of ADs in 
directory entries is handled somewhat differently, as described in Chapter III-3. If the caller is 
not allowed access to an AD in a directory entry, then Direct ory_Mgt . no_acces s is 
raised. 
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An object's passive version is modified only when a program or type manager explicitly 
passivates or updates the object. Passivating an object copies a particular active version to the 
passive version. 

These Passive_Store_Mgt calls create or update an object's passive version: 

Request_update 

Update 

Update_tree 

Update_with_alternate_rep 

Update updates a single object, for which the caller has rep rights. Update_tree updates 
a tree of objects; the caller must have rep rights for the root object. Request_updat e is 
used to update type-managed objects from outside their type managers; it requests that the 
object's type manager update an object. A type manager can refuse an update request by 
raising System_Exceptions . operation_not_supported. 

When an object is passivated from a particular active version, then all other active versions are 
marked as being obsolete. Any attempt to update an object from an obsolete version is 
rejected, with the Passive_Store_Mgt . outdate_ob ject_version exception. 

An object's passive version can have a different size than its active version. For example, 
passive versions that contain ADs are larger than the corresponding active versions. 
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11-3.1.8 Passivation Dependencies 

A passive object should normally only refer to other passive objects. This rule includes im- 
plicit references, such as the AD that every object has for its TDO. Thus: 

• If an object is passivated, its TDO should be passivated. 

• If an object is passivated, then its attribute list should be passivated. 

• If a TDO or an attribute list is passivated, then all attribute IDs and attribute value objects 
that it references should be passivated. 

• If an object is passivated, then any authority list protecting the object should be passivated. 

• If an object is passivated, then objects for which it contains ADs are normally passivated. 

As a general rule, if i4 depends on (references) B, then B should live as long or longer than A. 
Note that this rule should also influence when destroying a passive version is allowed. 

If your application attempts to access an object that has no active or passive version, then 
System_Exceptions . ob ject_has_no_representation is raised. 

11-3.1.9 Active-Only Objects 

Some types of object cannot be passivated; such objects are called active-only. For example, 
objects that exist only during program execution are active-only: sessions, jobs, processes, 
stacks, and transactions. 

Paradoxically, an active-only object type must have the passive store attribute! This is because 
the default behavior of objects is to be passivatable. The 

Passive_Store_Mgt . Set_refuse_f liters call assigns fields within a type's pas- 
sive store attribute record so that the type's objects are active-only. 

11-3.1.10 Passive Store Beiiavior of OS Object Types 

This section summarizes the passive store behavior of some common types of objects. The 
lists in this section are selective; see the "OS Object Types" appendix in the BiiN^/OS Refer- 
ence Manual for a list of object types. 

The following OS object types are kept in passive store by their type managers: 

normal directories 
files. 

The following OS object types can be passivated, but the application must handle creating and 
updating passive versions: 
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attribute ID 

attribute list 

authority list 

basic disk 

basic streamer 

data definition (DDef) object 

domain 

event cluster 

generic object 

instruction object 

name space 

pipe 

static data object 

type definition object (TDO). 

The following OS object types are active-only and cannot be passivated: 

job 

all opened device types 

certain system directories 

process 

session 

stack 

storage resource object (SRO) 

transaction 

windows (character or graphics). 

The following OS object type cannot be passivated but is permanently stored in the Qearing- 
house instead of in passive store: 

ID. 

11-3.1.11 Passive ADs 

Like any other object, a stored object can be referenced by many ADs, located in active ver- 
sions or in other stored objects. Before creating an object's passive version, you must store at 
least one AD to the object The first passive AD for an object is the object's master AD. All 
other passive ADs for an object are alias ADs. In certain circumstances, described in Section 
II-3.1.1 1.6, an AD is converted from an alias AD to a master AD, but there is never more than 
one master AD. 

n-3.1.11.1 Referencing Between Active Memory and Passive Store 

ADs can freely cross the boundary between active memory and passive store. A passive 
version can contain an AD for an active-only object. An active-only object can contain an AD 
for a passivated object. 

n-3.1.11.2 Master ADs 

The master AD determines the stored object's: 

• volume set 

• owner 

• authority list (if any). 
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Master ADs can be stored in directories or any other passive objects. 

A stored object is always on the same volume set as the object containing its master AD. 
Because master ADs cannot reference across volume sets, any passive object can be reached 
by a chain of master ADs from its volume set's root directory. The volume set containing an 
object's passive version cannot be changed; however the volume set may be moved to another 
node or even another BiiN™ system. Also the backup service provides techniques to archive 
volume sets or collections of objects within volume sets and then restore them on other volume 
sets (but with new object identities). 

A stored object's initial owner is the user ID for the process that stores the master AD. 

A stored object's initial authority list is determined as described in Chapter 111-3. 

Authority list evaluation uses whatever rights are on the master AD, even when evaluating 
rights for an alias AD. Normally a master AD should have aU type rights and no rep rights, as 
rep rights should only be granted within the type manager. For a passivated generic object, the 
master AD should normally have rep rights as well. 



n-3.1.11.3 Alias ADs 

AU passive ADs besides the master AD are aliases or alias ADs. Aliases can be freely created 
and deleted without restriction. Aliases can reference objects on other volume sets or other 
nodes. An alias may even reference an object on a volume set that is not moimted in the 
system. 

Alias ADs can be used for any object operations. While some operations require that an object 
have a master AD, no operation distinguishes between a master AD and alias when specifying 
an object to operate oa 

n-3.1.11.4 Restrictions on Storing Master ADs 

There are these restrictions on storing master ADs: 

1. If the object will use authority list protection, then its authority list must be set before the 
master AD is stored. 

2. A master AD cannot be stored after an AD for the object is stored in an active-only direc- 
tory. 

3. A master AD cannot be stored after an AD for the object is transmitted to another job via 
any of these techniques: 

• Job invocation parameter buffer 

• Event cluster signal 

• Remote procedure call 

• Datagram 

• Virtual circuit. 

4. A master AD cannot be stored after an application tries to store a master AD within a 
transaction, and then aborts the transaction. 

These restrictions will cause no problem if you create a passive object as follows: 
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1. Allocate the object's initial active version. 

2. If needed, explicitly set the object's authority list. 

3. Store the master AD. 

4. Passivate the object. 

5. If done within a transaction and the transaction aborts, recover aU the way to the first step, 
allocating a new object if the code retries. This avoids the problem of being unable to store 
a master AD for the previously allocated object. 

n-3.1.11.5 Master ADs and Passive Object Lifetimes 

In active memory there is no concept of a "master" AD, so why is one AD for each object 
singled out in passive store? There are several reasons, and one of the best reasons is that this 
solves the problem of knowing when to delete passive versions. Active objects are reclaimed 
either by job termination (for local objects) or by garbage collection. Garbage collection can 
reclaim objects with indefinite lifetimes by detecting when those objects can never again be 
accessed by any chain of ADs. However garbage collection is impractical in passive store, 
because ADs can reference between nodes in a network and even reference between mounted 
and dismounted volume sets! An exhaustive scan of aU filing volume sets at all nodes would 
consume too much network and disk bandwidth, but a scan that includes dismounted volume 
sets is completely impractical. Instead the master AD is singled out, and constrained to be on 
the same volume set as the object it references. If the master AD is deleted, then the object is 
deleted and reclaimed. The object can also be explicitly destroyed while the master AD still 
exists, but no further passive version of the object can be created. 

A passive object exists until its master AD is deleted, or until the object's passive version is 
explicitly destroyed. 

n-3.1.11.6 Transferring Mastership 

In two cases, deleting a master AD does not destroy a passive object O, but instead converts an 
alias AD to become the new master AD: 

• If the master AD is stored in a directory entry and other directory entries on the same 
volume set reference O, then "mastership" is transferred to one of the other entries. 

• If the master AD is stored in a non-directory object and other ADs in that object reference 
(9, then mastership is transferred to one of those other ADs. 

Note that the master AD always remains on the same volume set as the object it references. 
Note also that mastership is never transferred from a directory entry to a non-directory object. 

n-3.1.11.7 Object Trees 

An object tree is defined by a stored root object and all objects reached from it via a chain of 
master ADs. For example, if A contains a master AD for B which contains a master AD for C, 
then the object tree rooted in A contains C. 

All objects in an object tree have the same volume set. 

Several passive store caUs operate on object trees: Copy, Destroy, Request_update (in 
its default version), and Update_tree. 
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n-3.1.11.8 Passive ADs as Universal Identifiers 

A passive AD contains enough information to uniquely identify a passive object among all the 
passive objects ever created on any BiiN™ system anywhere at any time. Passive objects 
created on different volume sets, nodes, or systems can never be confused. A passive AD 
references one object in a universal address space, an address space that spans all objects ever 
created on any BiiN system, any where. 

11-3.1.12 Passive Store Behavior of Generic Objects 

Generic objects support all passive store calls. All Request_ passive store calls on generic 
objects require read rep rights. 

[[-3.1 .1 3 Passive Object Ciiaracteristics 

Figure II-3-3 shows a passive object and some of its associated characteristics. 



Directory 




Figure n-3-3. A Stored Object 



A passive object information record is also maintained for every passive object: 
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length 

create_time 

read_time 

write_time 

change_status_time 

owner 

auth_list 

volume_set 

node 



11-3.1.14 The Life History of a Passivated Object 

Figure II-3-4 shows a job creating and using a stored object: 

1. Creating the active version 

2. Storing the master AD 

3. Storing the passive version 

4. Changing the active version 

5. Updating the passive version. 

When the job terminates, the object's active version is deallocated but the passive version still 
exists. 
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Figure n-3-4. Life History of a Stored Object Part I 



Figure II-3-5 shows another job using and then destroying the same stored object: 

1. Retrieving an AD from the directory entry 

2. Accessing the object (transparently creates an active version) 

3. Destroying the passive version, the directory entry, and the active version. 
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Figure n-3-5. Life History of a Stored Object Part n 



11-3.1.15 Activation IVIodels 



Passive store supports two models of object activation: the multiple activation model and the 
single activation model. The choice of an activation model can be concealed within an 
object's type manager, and only the type manager implementer needs to be concerned with the 
choice. 



n-3.1.15.1 Multiple Activation 



In the multiple activation model, a single stored object can have multiple active versions in 
different jobs (Figure II-3-6). 
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PASSIVE VERSION 



PASSIVE 
STORE 




Figure 11-3-6. A Single Object can have Multiple Active Versions. 

In Figure II-3-6, if Job A updates the object, then Job B's active version is obsolete. Passive 
store keeps track of object versions and refuses updates from obsolete active versions, raising 
the outdated_ob ject_version exception in Passive_Store_Mgt. 

An application can handle the outdated_act ive_version exception by: 

1. Calling Reset_active_ver sion to make its active version current 

2. Redoing whatever changes it made to the active version 

3. Attempting the update again. 

A type manager can also define a version-out-of-date flag in the type's objects. Passive store 
then sets the flag in any obsolete active versions of the type. An application can check the flag 
before using an active version, resetting the active version if needed. Note that using the flag 
does not eliminate the outdated_ob ject_version exception; there can be communica- 
tion delays in setting the version-out-of-date flags. 

A job using a transaction can avoid any problems with an obsolete object version by reserving 
the object for the transaction. The object is reserved until the transaction is resolved. While a 
stored object is reserved, only updates associated with the reserving transaction are allowed. 
Passive_Store_Mgt . Reserve resets the caller's active version if it is obsolete, ensuring 
that subsequent code begins with the current version. 

Reserving frequenfly accessed objects for long periods can cause performance problems by 
delaying other jobs. 
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For global objects, there is one active version of the object per node where the object is ac- 
cessed rather than per job. 

n-3.1.15.2 Single Activation 

In the single activation model, an object is only activated in one home job. Other jobs that 
activate the object receive a token active version called a homomorph in place of ttie object. 
Those other jobs communicate with the object's home job to request operations on the real 
object. 

The type manager conceals the use of homomorphs. When an application requests an opera- 
tion on a homomorph, the type manager handles all the communication needed to perform the 
operation and return results. 

A type manager can distinguish between homomorph and real active versions by defining an 
is_homomorph boolean that is true in the homomorph template and that is false in all real 
passive and active versions. 

n-3.1.1S.3 Choosing an Activation Model 

In the single activation model, operations come to the object. In the multiple activation model, 
the object goes to the operations. In either case, the type manager's public interface should be 
the same. The choice of an activation model is an implementation decision, important only to 
designers of type managers, not to outside users. 

The multiple activation model: 

• Is often easier to implement 

• Brings the object to the operation (good for repeated operations on smaller objects) 

• Often requires code to handle clashes between concurrent and incompatible versions of the 
same object. 

The single activation model: 

• Is often more difficult to implement 

• Brings the operation to the object (good for larger objects such as files) 

• Does not cause clashes between multiple active versions of the same object 

11-3.1.16 Transaction Support 

Most passive store calls that change passive versions are transaction-oriented. A transaction- 
oriented caU participates in any default transaction. If there is no default transaction, then a 
transaction is created for the duration of the call. 

Object activation and Reset_active_version caUs normally can do dirty reads, reading 
a passive version written by another transaction before that transaction commits. An applica- 
tion can ensure that a committed version of an object is used by calling Re serve on the 
object. 

An object can reserve an object using either a write lock or a read lock. Write locks are 
exclusive and are not released until the enclosing root transaction is resolved. Read locks can 
be shared with other read lockers, and can be released early with explicit Release calls. 
Update and destroy caUs assert write locks if the affected objects are not already write-locked 
by the calling transaction. 
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Applications that use passive store may choose to maintain its transaction orientation. To do 
this, applications should group any sequence of logically dependent passive store/file/directory 
calls within a transaction. Chapter II-4 shows you how to use transactions. 

Stored objects can be concurrently accessed by multiple jobs using multiple transactions. A 
passive store call on an object can be refused because it is being used by a transaction with a 
more recent timestamp than the transaction enclosing the refused operation. Chapter II-4 
shows you how to handle timestamp conflicts. 

II-3.1.17 The Passive Store Attribute 

The behavior of passive store is customized for a particular object type by supplying a passive 
store attribute for the type. Each instance of this attribute is an object with the 

Passive_Store_Mgt . PSM_attributes_ob ject Ada type. 

11-3.1.18 Default Passive Store Behavior 

If an object type does not have the passive store attribute, then by default it supports all passive 
store calls. The default aUows copying of passive objects of the type and maps all Request_ 
caUs to the corresponding direct calls, regardless of what rights are on the AD supplied. 

11-3.1.19 Type Manager Support 

All the features described in this section are controlled by fields in a type's passive store 
attributes object. 

A type manager can supply type-specific subprograms to be called in response to any or all of 
the following Passive_Store_Mgt calls: 

Request_passive_object_info 

Request_release 

Request_reserve 

Request_reset_active_version 

Req-uest_set_timestamps 

Request_update 

A type-specific subprogram that refuses a request should raise 

System_Exceptions . operation_not_supported. 

A type-specific subprogram that makes multiple updates to passive objects, files, or directories 
can enclose its updates in a transaction, so that the type-specific subprogram is transaction- 
oriented. 

A type manager can refiise to allow copying of the type's stored objects by setting the 
copy_permitted boolean to false in the PSM attributes object. For example, if an account 
balance represents an amount of money, then it may be wise to prohibit copying of account 
objects! 

A type manager can define a locking area in its type's objects, using fields in the passive store 
attribute object. When an object is activated, a semaphore is created and an AD for the 
semaphore is placed in the first word of the locking area. Other words of the locking area are 
initially zero. When an active version is reset, the locking area is preserved and copied over 
from the preceding active version. 
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A locking area is needed when multiple processes in a job share an active version. The active 
version must contain a semaphore and possibly other information to synchronize access to the 
active version. Without a locking area, resetting the active version would lose the reference to 
needed synchronization information, such as a semaphore with a blocked process waiting to 
use the active version. 



11-3.2 Techniques 

After reading this section, you will be able to: 

• Create a passive object 

• Update a passive object 

• Request an update 

• Destroy a passive object 

• Copy a stored object tree 

• Get passive object information. 

Many of the examples are excerpted from the non-transaction-oriented body of the 
Stored_Account_Mgt_Ex example. This package extends the type manager for accounts, 
developed in Chapter VII-3, to use passive store. Appendix X-A contains complete listings for 
Stored_Account_Mgt_Ex and other units excerpted in this chapter. 

11-3.2.1 Creating a Passive Object 

Calls Used: 

Directory_Mgt . Store 

Stores a new directory entry. 

Passive_Store_Mgt . Update 

Updates an object's passive version. 

To create a stored object: 

1. Create and initialize the active object (as described in Chapter VII-3). 

2. Store a master AD for the object. 

3. Update the object, creating the passive version. 

The following excerpt from the Stored_Account_Mgt_Ex package body (non- 
transaction-oriented) shows how to create a stored object: 
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132 function Create_stored_account ( 

133 starting_balance: 

134 Long_Integer_Defs .long_integer := 

135 Long_Integer_Defs.zero; 
13 6 master: System_Defs .text; 

137 authority: 

138 Authority_List_Mgt .authority_list_AD := null) 

13 9 return account_AD 
140 

141 — Logic: 

142 — 1. Check the initial balance. 
143 

144 — 2. Allocate and initialize the account object. 
145 

14 6 — 3. Remove rep rights for the exported and master \ 
147 ~ AD. 

148 

14 9 — 4. Store the master AD. 

150 — Use "authority" as authority list to store the 

151 — account. If "authority" is null, the default 

152 — authority list of the target directory is used. 

153 — If there is none the caller's authority list in 

154 — the process globals is used. 
155 

156 — 5. Passivate the account object itself. 
157 

158 — 6. Return the AD without rep rights. 

159 is 

160 account: account_AD; 

161 account_untyped : System. untyped_word; 

162 FOR account_untyped USE AT account' address; 

163 — Account with no rep rights, viewed with 

164 — either of two types. 
165 

166 account_rep: account_rep_AD; 

167 account_rep_untyped: System. untyped_word; 

168 FOR account_rep_untyped USE AT 

169 account_rep' address; 

170 — Account with rep rights, viewed with 

171 — either of two types. 
172 
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173 begin 

174 — 1. Check the initial balance: 
175 

17 6 if starting_balance < Long_Integer_Defs .zero then 

177 RAISE insuf ficient_balance; 

178 

179 else 

180 — 2. Allocate and initialize the account object; 
181 

182 account_rep_untyped := Ob ject_Mgt .Allocate { 

183 size => {account_rep_object' size + 31) /32, 

184 tdo => account_TDO) ; 

185 account_rep.all := account_rep_object' ( 

186 balance => starting_balance) ; 
187 

188 — 3. Remove rep rights for the exported and 

189 — master AD: 
190 

191 account_untyped := Access_Mgt .Remove { 

192 AD => account_rep_untyped, 

193 rights => Object_Mgt .read_write_rights) ; 
194 

195 — 4. Store the master AD: 
196 

197 Directory_Mgt .Store ( 

198 name => master, 

199 object => account_untyped, 

200 aut => authority) ; 
201 

202 — 5. Passivate the account object itself: 

203 

204 Passive_Store_Mgt .Update {account_rep_untyped) ; 

205 

206 — 6. Return the account AD with no rep rights: 

207 

208 RETURN account; 

209 

210 end if; 

211 end Create_stored_account; 

11-3.2.2 Updating a Passive Object 

Calls Used: 

Pas sive_St or e_Mgt . Update 

Updates an object's passive version. 



Any operation that changes a stored object normally updates it. For example, the 
Change_balance call in Stored_Account_Mgt_Ex updates the affected account. 

267 account_rep. balance := 

268 account_rep. balance + amount; 

269 Passive_Store_Mgt .Update (account_untyped) ; 



11-3.2.3 Requesting an Update 



Calls Used: 



Passive_Store_Mgt . Request_update 

Requests a type-specific update. Defaults to Update_tree. 
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The following excerpt from the Make_ob ject_public_ex example shows storing a 
master AD and then requesting an update for an authority list object: 

58 aut_list: constant 

59 Authority_List_Mgt .authority_list_AD := 

60 Authority_List_Mgt.Create_authority (entries) ; 

67 Directory_Mgt .Store (aut_list_path, aut_untypeci) ; 

68 Passive_Store_Mgt .Request_update (aut_untyped) ; 

The excerpt uses Request_update instead of Update because the caller is not the type 
manager for authority lists and does not have rep rights. 



11-3.2.4 Destroying a Stored Object 



Calls Used: 

Directory_Mgt . Get_name 

Gets an object's fuU pathname (if any). 

Directory_Mgt . Delete 

Deletes a directory entry. 

Passive_Store_Mgt .Destroy 

Destroys a stored object tree. 



The Destroy_account call in the Stored_Account_Mgt_Ex example destroys an 
account's passive version, deletes one directory entry for the account, and deallocates the 
account's active version. If additional directory entries reference the account, then those 
entries become dangling references. (Any attempt to access the object via such a dangling 
reference raises System_Exceptions . ob ject_has_no_representation . Here is 
the code: 
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361 path_length: integer := 60; 

362 — Initial text length for name assigned 

363 — by "Direct ory_Mgt.Get_name". If 

364 — insufficient, then the value is 

365 — increased and the operation is 

366 — repeated. 

367 begin 

368 account_untyped := Access_Mgt . Import ( 

369 AD => account_untyped, 

370 rights => destroy_rights, 

371 tdo => account_TDO) ; 
372 

373 if account_rep. balance /= 

374 Long_Integer_Defs. zero then 

375 RAISE balance_not_zero; 
376 

377 else 

378 Passive_Store_Mgt . Destroy (account_untyped) ; 
379 

380 loop 

381 declare 

382 path_text : System_Defs.text (path_length) ; 

383 begin 

384 Directory_Mgt .Get_name ( 

385 obj => account_untyped, 

38 6 name => path_text); — out. 

387 if path_text. length > 

388 path_text .max_length then 

389 — Text was lost. Retry: 

390 path_length := path_text. length; 

391 else 

392 Directory_Mgt .Delete (path_text) ; 

393 EXIT; 
394 

395 end if; 

396 exception 

397 when Directory_Mgt .no_name => 

398 EXIT; 
399 

400 end; 

401 end loop; 
402 

403 Ob ject_Mgt .Deallocate (account_untyped) ; 

404 end if; 

405 end Destroy_account; 

NOTE: If an application knows that an object has only a single directory entry on its home 
volume set, and that the directory entry contains the object's master AD, then destroying the 
object is simpler: Just delete the directory entry containing the master AD and the passive 
version is also destroyed. 

11-3.2.5 Copying a Passive Object Tree 

Calls Used: 

Directory_Mgt . Store 

Stores an AD in a new directory entry. 

Passive_Store_Mgt . Create_copy_stub 

Creates a copy stub, used as the target of a subsequent Copy call. 

Passive_Store_Mgt . Copy 

Copies a tree of stored objects. 
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Suppose that passive store contains a tree of objects that you want to copy, such as a program 
containing many modules; perhaps you want a copy to create a variation of the program. 
Objects in the tree, all connected to the root by master ADs, are aU the parts of the program. 
The program also contains alias ADs that reference system services or shared library routines. 

When you make a copy of the program, you want to preserve the program's structure in your 
copy. For example, if object A in the program has a master AD for object B, then you want 
your copy of object A to contain a master AD for your copy of object B. Thus, copying must 
not just copy stored objects but sometimes remap ADs in the objects. On the other hand, if 
object B contains an alias AD for an object D that is not in the tree, then the copy of object B 
should contain an identical AD. This is the case when the program and the copy reference 
shared services or libraries that are not also copied. Figure II-3-7 shows how master ADs (A 
to B which maps into E to F) are remapped and alias ADs to objects outside the tree (B and F 
to D) are imchanged when a tree is copied. Any AD fixjm an object in the tree that references 
another object in the tree is remapped, even if it is an alias (C to B which maps into G to F). 



A COPY 
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>- MASTER AD 

■> ALIAS AD 

Figure n-3-7. Copying an Object Tree 



The passive store copy calls should not be used for backing up or restoring stored objects. See 

TM 

the BUN Systems Administrator's Guide for information about backing up or restoring stored 
objects. 

Some object types cannot be copied. For example, TDOs and attribute IDs carmot be copied. 
Objects tiiat correspond to physical devices cannot be copied. (What would it mean to "copy" 
a printer?) The copy_permitted boolean in a type's PSM attributes object determines 
whether objects of the type can be copied. The Set_refuse_f liters call assigns 
copy_jpermltted false. If any objects in a tree cannot be copied, then Copy raises 
Systein_Exceptlons . operatlon_not_supported. 

Copying an object tree copies passive versions and does not create active versions of any of the 
copied objects. 

When you make a copy, you create a new stored root object and possibly other new objects 
below it in a tree. But before this root object that does not yet exist can be stored, a master AD 
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must be stored for it! The master AD must be stored to determine the new object tree's 
volume set, owner, and authority lists. So that a destination master AD can be stored before 
copying an object tree, Passive_Store_Mgt provides the Create_copy_stub call, 
which creates a new "stub" object that is only used to: 

1. Store a master AD. 

2. Be the destination of a Copy operation. 

Copying a tree of stored objects thus has three steps: 

1. Create a copy stuby used as the target of the Copy caU. 

2. Store a master AD for the stub. 

3. Copy the object tree to the stub. 

The Named_copy_ex example procedure copies a source object tree to a destination object 
tree, given source and dest pathnames. This excerpt shows the three-step operation: 

62 source_AD := Directory_Mgt .Retrieve (source) ; 

63 dest_AD := Passive_Store_Mgt . 

64 Create_copy_stub (source_AD) ; 

65 Directory_Mgt .Store (name => dest, 

66 object => dest_AD); 

67 Passive_Store_Mgt .Copy (source_AD, dest_AD) ; 

11-3.2.6 Getting Passive Object information 



Calls Used: 

Passive_Store_Mgt .Request_passive_object_info 

Requests information about an object's passive version. 



The OS keeps much more information for passive versions than active versions: owner, au- 
thority list, volume set, node, size, and time created, last read, last written, and last modified in 
any way. 

The 01der_than_ex example function compares two stored objects to determine if the first 
was last written before the second. For example, 01der_than_ex can be used to determine 
if a machine instruction object is older than the associated source code object, requiring a 
recompile. 

The function uses Request_passive_ob ject_info rather than 
Get_passive_ob ject_inf o because it may not have rep rights on the objects being 
checked: 
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21 use Long_Integer_Defs; 

22 — Import "<" for long integers. 
23 

24 a_info: Passive_Store_Mgt .passive_ob ject_info; 

25 b_info: Passive_Store_Mgt .passive_ob ject_info; 

26 begin 

27 a_info := Passive_Store_Mgt . 

28 Request_passive_object_info (a) ; 

29 b_info := Passive_Store_Mgt . 

30 Request_passive_object_info (b) ; 
31 

32 if not a_info. valid or else not b_info. valid then 

33 RAISE Systein_Exceptions,bad_parameter; 
34 

35 else 

36 RETURN a_info . write_time < b_info.write_time; 
37 

38 end if; 

3 9 end 01der_than_ex; 

The valid field of the passive_ob ject_inf o record is false if the object does not have 
a passive version. 

11-3.3 Summary 

• Passive store is a distributed, reliable object filing service. 

• Use files instead of passive store if you do not need to store ADs and object types. Use 
files to port programs that use conventional file systems. Use files if you need fast random 
access to record-structured data. 

• An object can have zero or one passive versions and zero, one, or multiple active versions. 
These are all versions of a single object. 

• Active versions are created automatically when you try to access an object's representation 
within a job without an active version of the object 



Passive versions are created and changed by explicit update calls. 

The first AD stored for an object is its master AD, and must be stored before the object is 
stored. 

An object tree is a root object and all objects reached from it via a chain of master ADs. 
Some passive store calls operate on object trees. 

The passive store service detects conflicts between multiple object versions and raises ex- 
ceptions that can be handled by the callers. 

Passive store caUs are normally handled within type managers. 

Type managers can customize the passive store service for their type's objects by defining 
an instance of the passive store attribute. 



Storing Objects II-3-23 



rKliJLlJVUfN AK \ 



II-3-24 Storing Objects 



PRELIMINARY 



STARTING AND RESOLVING 

TRANSACTIONS 



4 



Contents 



Concepts II-4-2 

What Transactions Provide II-4-2 

Transaction Calls II-4-3 

Transaction Stacks II-4-3 

The Default Transaction II-4-3 

Participating in Transactions II-4-3 

The Transaction Service as a Coordinator 11-4-4 

Subtransactions II-4-4 

Avoiding Subtransactions II-4-4 

Rules for Using Transactions II-4-4 

Transaction Locking II-4-5 

Transaction Timeouts II-4-5 

Transactions and Job Termination II-4-6 

Avoiding Deadlocks with Timestamp Conflicts II-4-6 

Independent Transactions II-4-6 

Techniques II-4-6 

Using a Transaction II-4-6 

Avoiding Unnecessary Subtransactions II-4-7 

Using a Transaction and Recovering from Timestamp Conflicts II-4-8 

Summary 11-4-9 



Starting and Resolving Transactions II-4-1 



PRELIMIISAKY 

A transaction groups related operations so that either all the operations succeed or aU arc 
rolled back. 

Packages Used: 

Transact ion_Mgt 

Provides transactions used to group a series of related changes to objects 
so that either all the changes succeed or all are roUed back. 



This chapter introduces transactions and basic techniques for using transactions. Chapter 
IV- 10 describes transaction locking of files, opened files, key ranges, and records. 

Transactions are typically used to group changes to files or other objects stored on disk. For 
example, transferring $100 from one bank accoimt to another could be enclosed in a trans- 
action. If the change to either account failed or if the system crashed before all changes were 
made, then all changes would be undone. 

Transactions are also useful in less obvious ways. Even when a single record is inserted into a 
file, several disk writes may be needed to update indexes as well as the file's primary data area. 
The filing service uses a transaction to ensure that a failure within such a group of writes 
doesn't make the file and its indexes inconsistent. 



11-4.1 Concepts 



11-4.1.1 What Transactions Provide 

Transactions provide several services simultaneously to the developer: 

Atomicity Transactions are atomic or indivisible, either completely succeeding or 

making no changes at all. (Though atomicity only applies to those opera- 
tions that participate in the transaction, as described below.) 

Consistency Inconsistent and transitory states that your data passes through within a 

transaction are not visible from outside the transaction. For example, the 
state when one account has changed but not the other, or the state when 
one index has changed but not another, are not visible outside the enclos- 
ing transactions. (Consistency is enforced by type managers.) 

Crash Recovery Transactions work correctiy even if the system hardware or operating sys- 
tem crashes. Transactions in progress when a crash occurs are aborted as 
part of crash recovery. 

Synchronization Transactions synchronize with each other so that one transaction cannot 
access data being actively used by another transaction. 

Deadlock avoidance 

Transaction synchronization is designed so that deadlocks are not possible. 
An example of a deadlock would be if two transactions each blocked wait- 
ing for locks held by the other transaction. However, because each is 
blocked, the locks would never be released. The transaction service 
defines an ordering scheme that determines whether a particular trans- 
action is allowed to block for another particular transaction. If blocking is 
not allowed, an exception is raised. 
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Time limits When an application creates a transaction, it can specify a timeout that 

limits (aproximately) the total time taken by the transaction. 

Distributed service The transaction service is distributed. One transaction can include changes 
to objects at multiple nodes. 

Extensible service By default the transaction service can be used with any new type of local 
passivatable object. A type manager can also customize the transaction 
service for its object type. 

11-4.1.2 Transaction Calls 

Transact ion_Mgt defines three basic calls for transactions: 

Start_transaction 

Creates a transaction. 

Coiranit_transaction 

All changes within a transaction are done successfully. Terminate the 
transaction. 

Abort_transaction 

Something went wrong. Undo changes made within the transaction and 
terminate the transaction. 

Transact ion_Mgt includes several other calls, used for special purposes. The three basic 
calls are all that many applications need. 

11-4.1.3 Transaction Stack 

Transactions can be nested, and several transactions may be active at once. Each process has 
an associated transaction stack in its process globals. A process's transaction stack is initially 
empty. Creating a transaction pushes tiie new transaction onto the caller's transaction stack. 

li-4.1.4 The Default Transaction 

The transaction on top of a process's transaction stack is its default transaction. Many 
Transact ion_Mgt caUs have a transaction parameter that can be defaulted, indicating that 
the caller's default transaction should be used. Start_transaction pushes the new trans- 
action onto the caller's transaction stack. By default, Commit_transaction and 
Abort_tr ansact ion operate on the default transaction and pop it from the stack. 

11-4.1.5 Participating in Transactions 

A transaction only affects those calls that participate in the transaction. A participating call 
must be implemented in such a way that it can be aborted up to the time it is committed. Some 
calls only participate in a transaction if the caller has a default transaction. Other caUs par- 
ticipate in a transaction even if the caller has none, by creating a transaction for t^e duration of 
the call. If a System Services call participates in transactions, then its call description in the 

TM 

BUN I OS Reference Manual will state that it participates. Calls that affect structured 
transaction-oriented files, directories, and other passive objects often participate in trans- 
actions. 

It is important to realize that aborting a transaction does not roll back non-transaction-oriented 
actions! For example, screen I/O, printing a check, or assigning a program variable are not 
roUed back. 
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11-4.1.6 The Transaction Service as a Coordinator 

The transaction service acts as a coordinator for whatever type managers participate in a par- 
ticular transaction. Different transaction-oriented type managers may implement transaction 
locking, commital, and abortion differently. 

11-4.1.7 Subtransactions 

If Start_transact ion is called when there is already a default transaction, then the new 
transaction is a subtransaction or child transaction of that default transaction. A top-level 
transaction is a root transaction. Subtransactions and root transactions behave somewhat dif- 
ferently: 

• Committing a subtransaction does not make changes permanent but simply passes respon- 
sibility for the changes up to its parent transaction. 

• Committing a root transaction makes permanent any changes made within the root trans- 
action and within any committed subtransactions. 

• A transaction cannot be committed until all of its subtransactions are committed or aborted. 

• Aborting a subtransaction only aborts changes within the subtransaction and does not abort 
the parent transaction. 

• Aborting a transaction also aborts its subtransactions. 

Why use subtransactions? As far as atomicity and rollback, there seems to be no advantage to 
having transactions within transactions. There are two good reasons that subtransactions are 
used: 

1. To allow transaction-oriented functions to be combined in straightforward ways. A can call 
B which can call C, each procedure can enclose its code in a transaction, and tiiey will all 
work. 

2. To provide synchronization between concurrent processes within the same transaction. The 
transaction service uses transactions as the units being synchronized. Any concurrency 
within an overall transaction must be split into different subtransactions or the needed lock- 
ing won't happen. (To be precise, subtransactions for synchronization of concurrent 
processes in a transaction are only needed if there is data that may be used and locked by 
more than one of the processes.) 

11-4.1.8 Avoiding Subtransactions 

There is some overhead in creating subtransactions when they are not required. A transaction- 
oriented module may choose to check whether there is already a default transaction and only 
start a new transaction if there is not already one on the stack. 

11-4.1.9 Rules for Using Transactions 

These rules can help you in designing code that uses transactions: 

1 . Normally the section of code that starts a transaction should also commit it if successful 
and abort it if any exceptions occur. 

2. If possible, code between matching Start_transaction and 
Coinmit_transaction calls should not include operations that don't participate in the 
transactioa 
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3. If possible, code between matching Start_transaction and 
Commit_transaction calls should not include transfers of control out of that code 
block, such as RETURN, EXIT, or GOTO. If there are such transfers, then the transaction 
should be either committed or aborted on every possible path out of the block. 

4. Your code should normally not manipulate the transaction stack directly. 

5. If you spawn child processes within a transaction T and those processes need to participate 
in T, then: 

a. T must be passed to each child. 

b. Each child must push T on its transaction stack and then start a subtransaction. 

c. Each child must resolve its subtransaction before terminating. 

d. Each child should signal resolution of the subtransaction to the parent process. 

e. The parent process should not attempt to commit T until it is signaled that all the sub- 
transactions used by the child processes have been resolved. 

11-4.1 .1 Transaction Locking 

Whenever a transaction-oriented operation reads or writes data, it locks the data or some entity 
containing the data. Locking prevents concurrent changes and also keeps changes within the 
transaction from being visible to other transactions until such changes are committed. There 
are two type of locks asserted by a transaction: 

read lock Indicates that a transaction is using an entity and that the entity cannot be 

changed until the lock is released. 

A read lock allows other read locks but excludes write locks. 

A read lock can be explicitly released fix)m within the transaction that as- 
serted the lock. 

write lock Indicates that a transaction is using an entity and may change it. The 

entity cannot be read or written from outside the locking transaction until 
the locking transaction commits or aborts (except for dirty reads). 

A write lock is exclusive and does not aUow any other concurrent locks. 

A write lock cannot be explicitly released. Only resolving the locking 
transaction releases a write lock. 

The granularity of locking depends on the application or type manager. Transaction locks can 
be aquired on entire files, records within files, entries within directories, or entire passive 
objects. 

For reading only, an application can choose to bypass locks and dirty read data that may be 
involved in an uncommitted transaction. 

11-4.1.11 Transaction Timeouts 

Whenever a transaction is specified, an advisory timeout duration is specified. By default a 
system-supplied value, specified as a node configuration parameter, is used. A transaction that 
runs out of time is automatically aborted by the transaction service. A timeout is a lower limit 
on the actual time allowed. For example, if a timeout of 30 seconds is requested, then the 
actual timeout may occur after one minute. A timeout value is always finite-there is no 
concept of waiting forever~but can be very large. Timeouts help ensure that files, records, or 
other data structures don't remain locked indefinitely if a process holding a transaction lock is 
kiUed. 
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11-4.1.12 Transactions and Job Termination 

When a transaction is started, it is associated with the calling job. If that job tenninates and the 
transaction is not already committed or aborted, then job tennination aborts the transaction. 

11-4.1 .1 3 Avoiding Deadlocic with Timestamp Conflicts 

To avoid circular waiting, the transaction service defines a precedence scheme for transactions. 
Younger transactions will wait for older transactions but not the reverse. If an older trans- 
action does request a lock held by a younger transaction, then 

System_Exceptions . transaction_timestainp_conf lict is raised. The rules 
are different if the transactions involved are ancestor and descendant; see 
Transact ion_Mgt . Blocking_j)ermitted for details. 

An application can recover from a timestamp conflict by: 

• Aborting its transaction 

• Resetting any other state information, such as variables 

• Looping back in its code to the point where the transaction is started. 

The newly started transaction will be younger than the transaction holding the lock and will be 
allowed to wait. Multiple loop backs can occur due to (rare) concurrent activity. 

11-4.1.14 Independent Transactions 

Transact ion_Mgt . Start_independent_transaction can be called to create a 
new root transaction even if the caller has a default transaction. Consider a system accounting 
manager as an example of using independent transactions. Operations that consume or return 
system resources would update accounts on disk via the system accounting manager. Such 
updates are independent of whatever the application may be doing, and should be independent 
of any surrounding transaction. Otherwise, an abort of the surrounding transaction could erase 
all charges for resources used during the aborted operation. 

A process using an independent transaction should not try to get any lock held by an older 
imresolved transaction in the same process. This wiU cause the process to block imtil the older 
unresolved transaction times out 



11-4.2 Techniques 

After reading this section, you will be able to: 

• Use a transaction 

• Avoid unnecessary subtransactions 

• Use a transaction and recover from timestamp conflicts. 

11-4.2.1 Using a Transaction 



II-4-6 Starting and Resolving Transactions 



PRELIMINARY 



Calls Used: 

Transact ion_Mgt . Start_transaction 
Creates a transaction. 

Transaction_Mgt . Conimit_transaction 

Indicates that changes within a transaction are done. Makes the changes 
pennanent if the transaction is a root transaction. 

Transaction_Mgt .Abort_transaction 

Undoes all changes made within a transaction. 



The following excerpt from the Make_ob ject_public_ex example shows how to use a 
simple transaction: 

65 Transaction_Mgt .Start_transaction; 

66 begin 

67 Directory_Mgt .Store (aut_list_path, aut_untyped) ; 

68 Passive_Store_Mgt .Request_update (aut_untyped) ; 

69 Transaction_Mgt .Commit_transaction; 

70 exception 

71 when others => 

72 Transaction_Mgt . Abort_transaction; 

73 RAISE; 
74 

75 end; 

Note that the block containing the exception handler is only entered if the transaction is suc- 
cessfully started. Any exception causes the transaction to be aborted and the exception to be 
reraised. 

11-4.2.2 Avoiding Unnecessary Subtransactions 

Calls Used: 

Transaction_Mgt . Start_transaction 
Creates a transaction. 

Transaction_Mgt . Commit_transaction 

Indicates that changes within a transaction are done. Makes the changes 
pennanent if the transaction is a root transaction. 

Transaction_Mgt . Abort_transaction 

Undoes all changes made within a transaction. 



The following excerpt from the Stored_Account_Mgt_Ex transaction-oriented body 
shows how to start and resolve a local transaction only if the caller does not already have a 
default transaction: 
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195 trans: boolean := false; 

196 — True if a local transaction is started. 

219 — 4. Start a local transaction if there is not 

220 — a transaction on the stack: 
221 

222 if Transaction_Mgt .Get_default_transaction = 

223 null then 

224 Transaction_Mgt .Start_transaction; 

225 trans := true; 

226 end if; 

227 begin 

239 — 7. Commit any local transaction: 

240 

241 if trans then 

242 Transaction_Mgt .Commit_transaction; 

243 end if; 

244 exception 

24 5 — 8. If any exception occurs, abort any local 

24 6 — transaction, deallocate the account, 

24 7 — and reraise the exception: 

248 

24 9 when others => 

250 if trans then 

251 Transaction_Mgt .Abort_transaction; 

252 end if; 

253 Ob ject_Mgt .Deallocate (account_untyped) ; 

254 RAISE; 
255 

256 end; 

Note the use of the trans boolean to indicate whether or not a local transaction has been 
started. 

11-4.2.3 Using a Transaction and Recovering from Timestamp Conflicts 

Calls Used: 

Transact ion_Mgt . Start_transaction 
Creates a transaction. 

Transact ion_Mgt . Commit_transaction 

Indicates that changes within a transaction are done. Makes the changes 
permanent if the transaction is a root transaction. 

Transaction_Mgt . Abort_transaction 

Undoes all changes made within a transaction. 



The System_Exceptions . timestamp_conf lict exception is raised to prevent trans- 
action deadlocks, commonly when an older transaction requests an entity locked by a younger 
transaction. An application can recover from a timestamp conflict by aborting its transaction, 
resetting any other state information (such as variables), and looping back in its code to where 
the transaction is started. The newly started transaction will be younger than the transaction 
holding the lock and will be allowed to wait. Note that multiple loop backs can occur due to 
(rare) concurrent activity. The following example of using a transaction and handling times- 
tamp conflicts is excerpted from the Stored_Account_Mgt_Ex example's transaction- 
oriented body: 
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397 trans: boolean := false; 

398 — True if a local transaction is started. 

399 begin 

400 account_untyped := Access_Mgt . Import ( 

401 AD => account_untyped, 

402 rights => change_rights, 

403 tdo => account_TDO) ; 
404 

405 loop 

406 if Transaction_Mgt .Get_default_transaction = 

407 null then 

408 Transaction_Mgt .Start_transaction; 

409 trans := true; 

410 end if; 

411 begin 

412 Passive_Store_Mgt .Reserve (account_untyped) ; 

413 if account_rep. balance + amount < zero then 

414 RAISE insuf ficient_balance; 
415 

416 else 

417 account_rep. balance := 

418 account_rep. balance + amount; 

419 Passive_Store_Mgt .Update (account_untyped) , 

420 if trans then 

421 Transact ion_Mgt .Commit_transaction; 

422 end if; 

423 RETURN account_rep. balance; 
424 

425 end if; 

42 6 exception 

427 when System_Exceptions . 

428 transaction_timestamp_conflict => 

429 if trans then 

430 Transact ion_Mgt .Abort_transaction; 

431 else 

432 RAISE; 
433 

434 end if; 

435 when others => 

43 6 if trans then 

437 Transaction_Mgt .Abort_transaction; 

438 end if; 

439 RAISE; 

44 end; 

441 end loop; 

442 end Change balance; 



11-4.3 Summary 

• A transaction groups related operations so that either all succeed or all are rolled back. 



Using a transaction can be done with three simple calls that all use the caller's default 
transaction, with no explicit parameters. 



• Transactions synchronize with each other using read locks and write locks. 

• Younger transactions will wait for older transactions at a lock, but not vice versa. 

• Transactions can have timeout values. 
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Messages, incidents and exceptions are used to pass en-or messages between applications, 
programs, program modules, and users. This chapter discusses messages, incidents and excep- 
tions from a procedural viewpoint. 

Packages Used: 

History_Services 

Contains calls for using a job's history log files. 

Incident_Def s Defines incident and message types. 

Message_Services 

Provides calls to write messages from message files, message stacks, or 
message blocks. 

Message_Stack_Mgt 

Manages a process's message stack. 

System_Error_Recording 

Provides calls to record errors in a system log file. 



Traditionally, a program developer defines errors and exceptional situations and handles the 
messages that need to be sent when such situations occur. The BiiN™ system offers an ef- 
ficient and powerfiil mechanism for reporting errors and sending messages using incidents and 
messages. Help messages are similar to error messages but are managed separately. See 
Help_Text_Adin in tiie BiiN^IOS Reference Manual. 

An incident can be a normal program error, an Ada exception, an OS error, a test point as 
defined by a test point monitor, a situation that requires a message to the user or any situation 
that is reported outside the program. Each incident is assigned an incident code which iden- 
tifies a message and a severity level for tiie incident. Figure II-5-1 shows how an application 
developer can associate an error with an appropriate message using incident codes. 
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developer's source code 
) 



define error NN 

define incident code NN 
if error 

write nnesscge (incident 
code NN) 



incident 
code NN 



msg file ABC 



module 3 



number 1 



severity = 
error 



message file ABC 
^ 



message 
3.1 



English = not found 
German = "nicht gefunden' 



environment variable \i 



% user.language = english 




Figure 11-5-1. Incidents Associate Errors with Messages 



11-5.1 Concepts 



Using incidents greafly eases the development of messages and the handling of errors for large 
projects with coherent user interfaces. For example, once an incident has been defined for the 
common situation file not found, all developers on a large project can reference that 
incident code when the situation comes up and only the definer needs to maintain the actual 
message text and severity level for that incident 



11-5.1.1 Messages 



A message is the human-readable text associated with an incident. The message may contain 
text in more than one natural language (German, English, etc.) in a short or long fomi and 
contain parameters that can be substituted at the time the message is displayed. 

The Message_Services package provides the procedural interface for sending messages. 
The developer indicates specific message by passing an incident code, message block or com- 
plete message stack (see subsequent sections for descriptions of these message constructs). 
The human language and the message level are determined by the user's setting of CL vari- 
ables. 

From the user's point of view, a message contains a header, generated by the system, and the 
message text, derived from the possible texts in the message for that incident code according to 
the user's CL variables. 
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A header is automatically prepended to messages of warning, error and fatal status but 
not to messages of information status. The heading consists of the time of occurrence, the 
sender name and a single-letter code for the severity level. The appearance of a header and 
message is affected by CL variables (defined in a subsequent section). 

In the following message example, the time of the incident is 1 4 : 30 : 2 5, the sender is 
Invent or y_Files and the severity level is E (error). The CL variable msg . time is set to 
true, message . long is false and user . language is English. 

14:30:25 Inventory_Files - E: Insufficient access rights to read file. 

For more information about the contents of a message, see the BUN™ Command and Message 
Guide. 



11-5.1 .2 Message Files 



A message file contains the short and long forms of messages in one or more language varia- 
tions. The messages are indexed by a message index comprised of a module nxunber and 
sequential number and, optionally, by a message name. A message file is created for one or 
more applications by the manage .messages runtime command of the manage .program 
utility. The message_ob ject field in the incident code references the application's mes- 
sage file. 

For more information about creating a message file, see the BiiN™ Command and Message 



Guide. 

11-5.1 .3 Incident Codes 
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An incident is a BiiN construct that assigns a unique identifier, an incident code, to each 
error situation. An incident code references a message file, an individual message within that 
file and a severity level. 

It is recommended that each Ada exception be assigned an incident code. Situations that are 
not Ada exceptions may also have incident codes. For example, an incident code can be 
assigned when a user presses a special function key. 

An incident code record contains the following fields: 

me s s age_ob j e c t 

This field references the message file containing the message texts. The 
message file itself is created with the manage . messages utility. The 
software developer decides how to group messages (in a single file or in 
multiple files) and how to associate the message file with the software (to 
explicitly name the message file or to use a default message file). This 
field takes one of three values: 

• A valid AD to a message file. 

• A null AD indicating that the message file is the default message file. 
The default message file is created using manage . messages and is 
associated with the program via the OEO (Outside Environment Ob- 

TM 

ject, see the BiiN Command Language Executive Guide) using 

TM 

store . def ault_message_f ile. (See the BiiN Command and 
Message Guide for more information on these utilities.) 
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• A compiler-generated value (if the programmer did not define an in- 
cident code). This value may be an AD to some object other than a 
message file or a non-AD value. Either shows that a message is not 
defined for the incident code. In a program where the programmer 
does not define messages for program exceptions, for example the com- 
piler generates unique exception values. 

module A number from to 256K-1, inclusive, assigned to a program or module 

within a program. Combined with the incident number to identify an 
individual message within a message file. The incident module and in- 
cident number provide an index into the message file. 

number A number from to 4095, inclusive, assigned to the incident within the 

module where it is defined. 

severity A level of seriousness for the incident. Four severity levels are recognized: 

information, warning, error and fatal error. 

• information 

Not related to an error or warning; provides additional or helpful infor- 
mation. 

• warning 

Indicates an occurrence which deviates from the expected behavior but 
does not impede the expected outcome of an operation. 

• error 

Indicates that the operation generating the error cannot complete 
properly until the condition causing the error is corrected. 

• fatal_error 

Indicates an error of such severity that further processing is not pos- 
sible. 



11-5.1.4 Message Blocks 



A message block contains an incident code (which includes the message's module and number) 
and any message parameters. Calls that accept separate incident code and message parameters 
(see Message_Stack_Mgt) reformat them into message blocks. 



11-5.1.5 Message Stacks 



Program errors or incidents are frequently propagated through many layers of operations, espe- 
cially within a large application. The message stack provides a means of keeping a trace of 
any incidents that have occurred within a process along with specific information about each 
incident. 

The message stack is a fixed-length, open-bottomed stack. Each process has its own message 
stack. The message stack is large enough for two messages of maximum size. The message 
stack is open-bottomed so that if another message is pushed on a fiill stack, the bottom mes- 
sage on the stack is lost. 

A message stack contains message block entries. CaUs that accept separate incident code and 
message parameters (see Mes sage_Stack_Mgt) reformat them into a message block which 
is then pushed onto a message stack. Entries are retrieved from the message stack as message 
blocks. 
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A message block is pushed onto a message stack whenever more specific infonnation than that 
associated with the exception itself would be useftil to someone debugging the program. 
(Messages are not automatically pushed on the message stack; they must be explicitly pushed 
on the stack by the exception handler.) Large user- written applications may make use of the 
message stack in a similar manner. 

When a process temiinates due to an unhandled error propagating out of its top level proce- 
dure, its message stack contains the history of that error's propagation. The first message 
block on the message stack is the actual error that caused termination. The subsequent mes- 
sage blocks contain information about the various levels of the system through which the error 
propagated. 

It is good practice, although not required, for a program that catches and handles an incident or 
error to clear the message stack. Otherwise, on a later incident or error, the message stack 
contains the history of the previous (already-handled) errors as weU as the error that caused 
tennination. This can be confusing to someone debugging the program. 

See the Mes sage_Stack_Mgt package for more information about message stacks. 

11-5.1.6 Messages and Exceptions 

An exception is the Ada construct that signals the occurrence of errors or other exceptional 
situations that arise during program execution. Raising an exception causes normal program 
execution to be abandoned in order to deal with the error or situation. 

Each exception may be, but is not required to be, associated with an incident. When a 
programmer wants to define a message for an exception, an incident code is assigned to that 
exception. 

11-5.1.7 CL Variables That Affect l\/lessages 

The following CL variables affect how a message is displayed. 

user . verbose Determines whether information level messages are displayed. Messages 
which report job status, for example, may be displayed only in verbose 
mode. The developer can set verbose_only to true in order to make 
informational messages display when calling 
Message_Services . Write_msg or similar calls. When 
user . verbose is false, only warning, error and f atal_error 
messagess are displayed. 

user . language Controls which language variant of a message is displayed. If the message 
does not exist in the desired language, the message's default language 
variant is displayed (the first variant stored in the message file). 

msg . long_t ext Controls which form of the message (short or long) is displayed. If false 
(the default), the short form is displayed, otherwise the long form. If the 
selected level does not exist, the other level is displayed. 

ms g . t ime Controls whether the time the incident occurred should be displayed as 

part of the message header. 

The built-in command set . variable sets or changes the values of user CL variables. 
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11-5.1.8 How CLEX Handles Messages From Terminated Jobs 

An exception for which no exception handler exists will tenninate a job. All messages pushed 
on the message stack (up to the maximum it can hold) prior to termination will be on the stack. 
A message, if any, associated with the terminating exception will not appear on the stack. 

11-5.1 .9 Message Utilities 

A message file can be created and updated with the manage . me s sage s runtime command 
of the manage .program utility. The runtime commands of manage .messages include 
change, list, remove, set . language and store. 



II-5.1.10 History Files 



Message_Services automatically records messages in a job history log if one is installed. 
Users can turn off message recording via a boolean parameter in the various Write_msg 
calls. The History_Services . Record_message caU takes an incident code and sends 
the corresponding message to the job's history_log file. Thus a job can maintain a record 
of any messages that were sent during the course of the job. 

A user can have a history installed for a logon session if the CL variable 
logon . install_history_log is true. 

A job can have a history installed if: 

• The control option : : hi st or y_log was called in the invocation of the job, or 

• The built-in command start. history_log was called, or 

• The package History_Services was used to create, open and set a history_log 
file. 



11-5.2 System Error Log 



The System_Error_Recording package provides calls for recording system errors on a 
system error log. This log is a record-oriented, sequential file. The error information can be 
specified as an incident code with from zero to five parameters or as a message block. The 
record layout is defined by the type Monitor_Def s .monitor_message. 
System_Error_Recording . Get_event_cluster provides access to an event cluster 
that gets signalled whenever an error is recorded to the system error log file. The system error 
log is only for trusted type managers such as device drivers. 



11-5.3 Techniques 

After reading this section, you will be able to: 

• Define application messages 

• Write a message 

• Associate an incident code with an exception 

• Replace OS exceptions with application messages 
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• Use predefined OS messages 

• Push a message when raising an exception 

• Qear the message stack when handling an exception 

• Write a message with acknowledgement 

• Record history entries. 

Code examples in the following sections are excerpts from the At_Cnid_Ex, 
At_Support_Ex, Inventory_f ile, Create_Naine_Space_Cmd_Ex, 
Example_Messages and Inventory_Files example programs that are listed in their 
entirety in Appendix X-A. 

11-5.3.1 Defining Application Messages 

Declarations Used: 

Incident_Def s . incident_code 

A representation for errors, warnings, information, exceptions and system 
errors. 



The system recognizes four types of messages: 

• Those used to identify exceptions 

• Those used to identify other messages to be pushed onto a process's message stack 

• Those used to identify operating system errors, and 

• Those used as test point monitoring codes. 

All of these message types may be represented by lncident_Def s . incident_code. 
This incident code contains the severity of the incident and a message file reference and 
index (module and number) which uniquely identifies message text associated with the in- 
cident. 

To create an incident code, declare a constant of type Incident_Def s . incident_code 
with the following fields: 

message object An AD to tiie message object, 

module Number of the module in which this incident is defined, 

number A number for the specific incident within the module, 

severity A severity level. 

When the application developer assigns a module number and a sequential number to an in- 
cident, these numbers must be unique within the environment in which they are visible. 

The following example from At_Support_Ex defines an incident code: 
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20 — Exception Codes: 

21 msg_obj: constant System. untyped_word := 

22 System. null_word; — use oeo 
23 

24 time_format_error_code: constant Incident_Def s. 

25 incident_code := ( 

2 6 module => 0, 

27 number => 1, 

28 severity => Incident_Defs .error, 

29 message_ob ject => msg_obj) ; 

The fields of the time_f ormat_error_code incident code contain the following values: 

me s s age_ob ject 

Declared as a null AD (uses the default message file specified in the 
programs Outside Environment Object). 

module The module number of At_Support_Ex. The value is 0. 

number The number of this incident in this module. The value is 1. 

severity The value error. 

The actual text of the message associated with an incident can be stored in a message file by 
one of the following three methods. 



n-5.3.1.1 In the Source File 



Include the actual text of the message in the source file with tagged comment lines which can 
be identified and extracted by manage . messages. The tag for the comment line in the 
example code is *D* (that is, *D* immediately follows the two dashes of an Ada comment 
line. The extract . tagged_commands utility extracts tagged lines and passes them to 
manage . me s sages which creates the message file. In this method, the text of the message 
is physically close to the definition of its associated incident, an advantage for small programs 
with few messages. 

In the following code example, tagged comment lines are used to include message text in the 
program source file: 

4 5 — Exceptions: 

4 6 

4 7 — *D* manage. messages 

4 8 

4 9 time_format_error : exception; 

50 — Occurs when the time was not input in a proper 

51 — format 

52 — *D* store 1 time_format_error \ 

53 — *D* : short = "$pl is an improper time specification 

54 — *D*The correct format is hh [ :mm[ : ss [ .dd] ] ] " 



n-5.3.1.2 In a Command File 



Include the text of messages in a command file which is passed to manage .messages 
which in turn creates the message file. This method allows aU messages for a program to be 
kept in a single file which can be edited or updated using any text editor. 

n-5.3.1.3 Using manage .messages 

Invoke manage . program then run manage . messages and use its runtime commands to 
create and update the text of messages. This method allows easy listing, searching and updat- 
ing of individual message texts, an advantage for larger applications where consistency and 
coherence among messages is desirable. The following example shows the declaration for the 
not_on_f ile message, the tagged lines used by manage .messages to include the mes- 
sage in a message file and the declaration of the exception associated with the message. 
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104 not_on_file_code: constant 

105 Incident_Defs . incident_code := ( 

106 message_object => 

107 Inventory_Messages .message_ob ject, 

108 module => module, 

109 number => 5, 

110 severity => Incident_Def s. error ) ; 
111 

112 — *D* store tmodule = $module \ 

113 — *D* :number = 5 \ 

114 — *D* :msg_name = not_on_file \ 

115 — *D* : short = "There is no parts 

116 — *D* record for part ID "$pl<part 

117 — *D* ID (index value) >' does not 

118 — *D* exist." 
119 

120 not_on_file: exception; 

121 pragma exception_value<not_on_f ile, 

122 not_on_f ile_code) ; 

123 — Raised by "Read_parts_record" and 

124 — "Rewrite_parts_record" . 

For more information on creating message texts, see the BiiN^ Command and Message Guide. 

11-5.3.2 Writing a Message 

Calls Used: 

Message_Services .Write_msg 

Foraiats and writes a message. 



To write a message to the user's message window, specify: 

ms g_id Incident code for the message. 

param ( 1 . . . 5 ) Parameter(s) to insert into the message text, if any. 

device Opened device to which message is sent. The user's opened message win- 

dow by default. 

For example in the At_Cmd_Ex example program, the message associated with incident code 
prior_time_warning_code is written as follows: 

168 Message_Services.Write_msg ( 

169 msg_id => At_Support_Ex.prior_time_warning_code) ; 

For more information on writing message texts to accept message parameters, see the BiiN^ 
Command and Message Guide. 

11-5.3.3 Associating an Incident Code With an Exception 

Declarations Used: 

pragma exception_value 

Binds the value of an exception with a named incident code. 



It is often useful to associate an Ada exception with an incident so that when the exception is 
raised, the incident code is implicitiy available, pragma except ion_value associates an 
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exception with an incident code. This binding is illustrated with the following example from 

Invent ory_File: 

104 not_on_file_code: constant 

105 Incident_Defs .incident_code := ( 

106 message_object => 

107 Inventory_Messages.message_ob ject, 

108 module => module, 

109 number => 5, 

110 severity => Incident_Defs .error) ; 

120 not_on_file: exception; 

121 pragma exception_value {not_on_file, 

122 not_on_file_code) ; 

123 — Raised by "Read_parts_record" and 

124 — "Rewrite_parts_record" . 

11-5.3.4 Replacing an OS Exception With an Application Message 

When the operating system raises one of its exceptions, that exception can be replaced with a 
more detailed local message. The following code from the Invent or y_Files example 
program shows an update operation. When it is unsuccessful, 

Record_AM. invalid_record_address is automatically raised. The package raises its 
own exception, not_on_f ile and writes an explanatory message. 

230 

231 — Rewrite (update) parts record: 

232 

233 Record_AM.Keyed_Ops .Update_by_key ( 

234 opened_dev => parts_file, 

235 buffer_VA => parts_record' address, 

236 length => parts_record' size/8, 

237 index => part_ID_index_name) ; 
238 

239 exception 
240 

241 when Record_AM. invalid_record_address => 

242 Message_Services.Write_msg ( 

243 msg_id => not_on_f ile_code, 

244 paraml => Incident_Defs.message_parameter ( 

245 typ => Incident_Defs.txt, 

246 len => part_ID_index_str. length) ' ( 

247 typ => Incident_Defs.txt, 

248 len => part_ID_index_str. length, 

249 txt_val => part_ID_index_name) ) ; 

250 RAISE not_on_file; 

11-5.3.5 Taking Advantage of Predefined OS Messages 

The /msg directory contains predefined message fiiles. These messages may be used by ap- 
plication programs. It is advisable to use the messages in the same context for which they 
were originally created. These messages may be reviewed with the list command of the 
manage .messages run-time command of the manage . program utility. 

11-5.3.6 Pushing a Message Wlien Raising an Exception 

Calls Used: 

Message_Stack_Mgt . Push_msg_l_jparam 

Pushes a message block with one parameter onto the caller's message 
stack. 
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The BiiN Operating System often pushes a message to the message stack prior to raising an 
exception. Applications may also push messages on the stack when raising exceptions in order 
to provide more information concerning the reason for abnormal program termination. 

In the following example from Invent ory_Files, the exception handler for the 
Read_parts_record procedure catches an attempt to read a part that is not on the file and 
writes the message associated witii the not_on_f ile_code. It then pushes the 
not_on_f ile message on the message stack. 

126 Message_Services.Write_msg( 

127 msg_id => not_on_file_code, 

128 paraml => Incident_Defs.message_parameter ( 

129 typ => Incident_Defs.txt, 

130 len => part_ID. length) ' ( 

131 typ => Incident_Defs.txt, 

132 len => part_ID. length, 

133 txt_val => part_ID)); 

134 Message_Stack_Mgt .Push_msg_l_param( 

135 not_on_file_code) ; 

11-5.3.7 Clearing the Message Stack When Handling an Exception 

Calls Used: 

Message_Stack_Mgt . CI ear_mes sages 

Discards all messages on the caller's message stack. 



It is good practice, although not required, for a program that catches and handles an incident or 
error to clear the message stack. Otherwise on a later incident or error, the message stack 
contains the history of tiie previously handled errors as well as the error that caused termina- 
tion. This can be confusing to people debugging tiie program. 

In the following example from Invent ory_Files, the exception handler for the 
Read__parts_record procedure catches an incomplete key value and writes the message 
associated with the invalid_part_ID_code. It then clears the message stack before 
pushing the current message. 

143 Message_Services . Write_msg( 

144 msg_id => invalid_part_ID_code, 

145 paraml => Incident_Defs .messagejparameter { 

146 typ => Incident_Defs.txt, 

147 len => part_ID. length) ' { 

148 typ => Incident_Defs.txt, 
14 9 len => part_ID. length, 

150 txt_val => part_ID) ) ; 

151 Message_Stack_Mgt .Clear_messages; 

152 Message_Stack_Mgt .Push_msg_l_param( 

153 message_id => invalid_part_ID_code, 

154 paraml => Incident_Defs .message_parameter { 

155 typ => Incident_Defs.txt, 

156 len => part_ID. length) ' ( 

157 typ => Incident_Defs.txt, 

158 len => part_ID . length, 

159 txt_val => part_ID) ) ; 
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11-5.3.8 Writing a [\/Iessage Witli Acknowledgement 

Calls Used: 

Message_Services.Acknowledge_msg 

Writes a message with no <LF>, then reads and parses the user's response. 



To write a message and receive a response from the user, use 

Message_Services .Acknowledge_msg. 

The message should explain to the user the choices on which his response must be made. A 
positive acknowledgement currently results from yes, ja, true or +. Any other input, in- 
cluding just <CR>, returns false. The words yes, ja and true can be abbreviated to one 
letter. 

If an opened device is specified, it is used both for writing a message and reading the response. 
Otherwise, the device from the caller's user_dialog entry in process globals is used. In 
any case, the device must be interactive as defined by 

Device_Def s . device_inf o . coiiimon_inf o. The call does nothing and returns false if 
the device is noninteractive. 

If writing or reading fails for any reason, false is returned. 

The following code is from Exainple_Messages (the acknowledge message) and 
Create_naine_space_cmd_ex (code requesting affirmation from the user before storing a 
new name space as a directory entry). 

63 overwrite_query_code: 

64 constant Incident_Defs. incident_code := 

65 (0, 4, Incident_Defs. information, msg_obj); 
66 

67 — *D* store :module=0 :number=4 \ 

68 — *D* :msg_name=overwrite_query_code \ 

69 — *D* : short = \ 

70 — *D* "$pl<pathname> exists. Overwrite it?" 

261 — Confirm overwrite: 

262 

263 overwrite := 

264 Message_Services .Acknowledge_msg( 

265 Example_Messages. 

266 overwrite_query_code, 

267 Incident_Defs . 

268 message_parameter { 

269 typ => Incident_Defs.txt, 

270 len => name .max_length) ' ( 

271 typ => 

272 Incident_Defs.txt, 

273 len => 

274 name.max_length, 

275 txt_val => name) ) ; 

276 end if; 



11-5.3.9 Recording History Entries 
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Calls Used: 

History_Services .Re cor d_m.es sage 

Records a message in an opened history file, or in the caller's current job 
history, returning the record ID. 



To record a message in a job's history_log file, record an individual message explicitly 
via History_Services . Record message. This call returns a record ID. 



11-5.3.10 Summary 



An incident is a BiiN construct that assigns a unique identifier, an incident code, to each 
error situation. 

An incident code identifies a message and a severity level for an incident. 

An exception is the Ada construct that signals the occurrence of errors or other exceptional 
situations that arise during program execution. 

A message is the human=readable text associated with an incident. 

A message file contains the short and long forms of messages in one or more language 
variations. The message_ob ject field in the incident code references the application's 
message file. 

A message block contains an incident code (which includes the message's module and 
number) and any message parameters. 

A message stack is a fixed-length, open-bottomed stack that provides a means of keeping a 
trace of any incidents that have occurred within a process along with specific information 
about each incident. 
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Part III 

Directory Services 



This part of the BUN™/ OS Guide gives concepts and techniques for naming objects in direc- 
tories and for protecting stored objects from unauthorized access. 

This part contains these chapters: 

Understanding Directories 

Explains basic concepts needed to understand the system's directory 
mechanism. 

Using Directories Provides techniques for using directories. 

Protecting Stored Objects 

Shows how to protect objects using IDs and authority lists. 

Using Name Spaces 

Shows how to use name spaces Gists of directories). 

Creating Symbolic Links 

Shows how to use symbolic links between directories or directory entries. 

Directory Services contains the following services and packages: 

Naming Service 

Directory_Mgt 

Name_Space_Mgt 

Symbolic_Link_Mgt 

Protection Service 

Author ity_List_Mgt 
Identification_Admin 
Identification_Mgt 
User_Mgt 
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Figure IQ-l-l. Directories Contain <Name, AD> Pairs 



Directories allow you to associate a name with the object's AD and store the <name, AD> pair 
in a directory (Figure ni-1-1). Given a full pathname, you can find the object associated with 
that name. 

TM 

This chapter explains in more detail the concepts of BiiN directories. 



III-1.1 Directory Structure 



In other systems, directories map names to files or directories only. By contrast, the directory 
service allows an AD for any type of object to be stored in a directory. This includes files, 
other directories, devices, programs, IDs, authority lists, data definitions, version groups, form 
definitions, report definitions, and so on. 

All names within a given directory must be unique. The storage of names in directories is 
case-sensitive; that is, lowercase characters are distinct from uppercase (for example, 
My_F i 1 e is distinct from my_f i 1 e). 

Examples of valid names include: 



ADA_source 
Chapter-1.12 
%_of_cost 
2 



tools 

673-59-1257 

#s_per_sq_inch 



A directory can contain another directory (a subdirectory), allowing for conventional tree 
structures and hierarchies. For example, in Figure in-1-2, src is a subdirectory of joe. A 
directory that contains an entry or another directory is tiiQ parent of that entry or directory. 

A directory can also contain an alias entry. An alias entry is another name for an AD that 
already has a name. Because an AD can have any number of aliases, you can set up directory 
structures that are not limited to trees or strict hierarchies (Figure III- 1-2). 
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Figure in-1-2. A Directory Structure with Aliases 



In Figure III-1-2, an example of an alias is the name module 1 in directory joe/ sr c. Joe 
has a name for this module as does Sue. Both names reference the same underlying object. 
Note that an alias can reference an AD on a different node in the distributed system. Deleting 
an alias has no effect on the referenced object, so Joe can delete his module_l without 
affecting Sue's. 

Directories and subdirectories are common in other systems. Using BiiN™ directory services, 
however, a set of connected directories is not limited to tree structures. A single object can be 
stored in the same directory under different names (aliases) or in other directories under the 
same or different names. Directories can be linked together into meaningful, networked struc- 
tures. 

{correct this later. 6/24/88 - stanf } Cycles are allowed; that is, in Figure 111-1-2, Sue's file 
module_l can be aliased to directory sue, even though sue is a parent of sue/ src. 

III-1.1.1 Pathname Syntax 

See the "Pathname Syntax" appendix in the BiiN I OS Reference Manual for an explanation of 
the different kinds of pathnames and their syntax. 

III-1.1.2 Alias Entries and l\/laster Entries 

Calling Directory_Mgt . Store to store an AD with a name for the first time places an 
entry in the directory and the associated passivated AD is the master AD. Subsequent 
Stores of an AD for which a master already exists result in alias entries. 

Storing an AD to an object doesn't always produce a master AD for the object. Only the first 
AD to cross the boundary between active and passive space as a result of a Store (or 
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Great e_directory) or update of an object which contains the AD produces a master. If 
the first AD to cross the boundary from active to passive space does so as a result of some 
other operation, then subsequent Stores of the AD (or updates of its container) will NOT 
produce a master AD. 



111-1.1.3 Symbolic Links 



A symbolic link contains a pathname. Symbolic link evaluation retrieves whatever AD is 
stored with that pathname. If an AD to a symbolic link is stored in a directory entry, then 
retrieving from the entry does not return the entry's AD. Instead, an AD to the object 
referenced by the link is returned. 

Aliases and symbolic links provide two ways to associate an AD with different names. 

Both are useful in that they allow the user flexibility in the naming and symbolic referencing of 
objects. 

Both aliases and symbolic links may be stored in any directory for which the user has store 
rights. 

However, using an alias in a Directory_Mgt . Delete causes only the alias to be deleted; 
the imderlying object is not affected. Using a symbolic link in a Directory_Mgt . Delete 
causes the symbolic link object itself (not the object referenced by the link's value) to be 
deleted. 

An alias has the following advantages: 

• It references the same object type. 

• The alias may inherit "mastership," so that even if the master pathname is deleted, there 
may still be a named reference to the object (inheritance requires that the alias entry reside 
on the same volume set as the master AD). 

An alias has this disadvantage: 

• It references the same object type, i.e, the associated AD is "object instance" specific, so 
that if the underlying object is deallocated, the alias may be left as a dangling reference. 
For instance, if you have a program /joe/prog that is aliased by / joe/bin/p and you 
replace / joe/prog with a revised version of the same program, the / joe/prog alias 
will point to the outdated version. If the alias was / vs 2 / j oe /prog, it would be a 
dancing reference to the old version. 

A symbolic link has the following advantages: 

• It references an object NAME. Any object can exist imder this name at one time or 
another. This means you can also update an object under that name and not end up with a 
dangling reference as for aliases (you might want to replace an existing program with a 
revised version, or some such). 

• You can set its value to a CL variable, for example, $mybin, which gives you a great deal 
of flexibility. 

A symbolic link has the following disadvantages: 

• The symbolic link cannot inherit "mastership" for the object referenced by the link's value. 
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• The associated link value is "name" specific, so that if a different object is stored under the 
same name, the user may end up accessing something incompatible with the type needed. 

III-1.1.4 Protecting Directories and their Contents 

Most OSs detennine who has access to what programs and data using an owner/group/world 
mechanism. Access to programs and data depends on whether your group (or you, or 
everyone) has the authority to read, write, or execute a file. 

The BiiN™ system extends the familiar three-level owner I group I world protection to flexible, 
multi-level protectioa This is done with authority lists and IDs. The associated authority list 
protects the object. (Qiapter III-3 discusses authority Usts and IDs in more detail.) 

Each caUer is represented by a list of IDs which that caller can portray. By default, these IDs 
are the user ID, ux_group, and world, which the caller acquires during the logon session. 
When the caller tries to access a protected object, the caller's IDs are compared with the IDs in 
the authority list to determine access. 

There can be any number of IDs in the authority list (Figure EI- 1-3), as opposed to the three 
allowed in owner I group I world protection. TTie authority list contains a list of IDs and 
associated type rights. For each ID, the type rights specify what the ID holder can do with the 
object protected by this authority list 
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Figure in-1-3. A Directory is Protected with an Authority List 

For example, according to the authority list associated with directory joe in Figure III- 1-3, a 
caller holding the ID for pro j_manager has list rights, and can list the contents of the 
directory. But a caller holding the ID for gue st has no type rights and cannot access that 
directory at all. 

Chapter ni-3 discusses authority lists and IDs in more detail. 

III-1.2 The Clearinghouse: Naming in a Distributed System 

The Qearinghouse maintains the database showing where objects are actually stored in a dis- 
tributed system, by keeping track of where each volume set is mounted. (A volume set is a 
logical disk, and contains programs and objects of various types as well as files.) 
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Directory_Mgt goes to the Clearinghouse to find the node and volume set, then to the 
node and volume set to find the named object. This process is transparent to the caller, so that 
the caller does not need to know which node an object is stored on. (The caller also doesn't 
need to know about the Qearinghouse, beyond imderstanding its role in finding named 
objects.) 

To illustrate, Figure 111-1-4 shows the process Direct or y_Mgt goes through to return an 
AD for a fiiU pathname. 
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Figure III-1-4. Directory_Mgt uses the Clearinghouse to Resolve Network Names. 

When specifying an organization or full pathname, for example to access an object or service 
in a different /organization/domain in the distributed system, it is helpful to understand a little 
about how objects and services are stored and named over the distributed system. The dis- 
tributed storage-and-naming system worics like this. 

Every object that has been Stored with Directory_Mgt . Store exists on a volume set, 
which is a logical disk. There can be many names for any volume set, and many volume sets 
attached to a particular node. 

All the volume sets attached to all the nodes in a distributed system form the passive space. 
The passive space is grouped into naming domains, so-called to distinguish them from other 
kinds of domains in the BiiN™ system. A naming domain is identified by the org/ dom part 
of a pathname; for example, spirit_motor s/engineer ing. Each volume set is as- 
signed to a naming domain, and a naming domain can contain one or more volume sets. All 
volume sets in a naming domain must have unique names. 
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Objects in the passive space are identified by pathnames. The BiiN™ system needs a way to 
identify objects anywhere in the distributed system, no matter where they are. To refer to an 
object in the same naming domain, you can simply use a node or relative pathname. To refer 
to an object in a different naming domain, you must use a pathname that begins with two or 
more slashes (organization or full pathname). The rest of this paper describes how full path- 
names are built. 

In BiiN™ systems, there are many valid pathnames for any object. However, there is one 
standard pathname, called the canonical patname, which uniquely identifies a passive object 
anywhere in a network of BiiN™ systems by specifying the volume set it is on and its path- 
name within the volume set. All utilities that result in full pathnames show them in canonical 
form. For example, the output of list . current_directory is always a canonical path- 
name. 

A canonical fuU pathname looks like this: 
// /org/ dom/vs/vsname/ pathname 

The parts of this pathname have the following meanings: 

org A BiiN™ distributed system can be divided into several organizations. The 

organization is the largest division in a distributed system. For example, a 
system for a large corporation might be divided by division (systems, 
components, and software) or by site (portland, new_york, 
maui, and berlin). 

dom Each organization can be divided into several domains. For example, the 

organization systems could be divided into the domains 
engineering, doc, marketing, manufacturing, and 
shipping, or alternatively f irst_f loor, second_f loor, and 
basement. 

vs vs is a predefined directory in each naming domain that holds the names 

of aU volume sets in the naming domain. The literal word vs in a path- 
name indicates that the rest of the pathname refers to an object on one of 
the volume sets in the network, (vs is actually one of several 
environments in each domain. Two other environments are home and 
node, which will be discussed later. However, the vs environment is 
always used in the canonical pathname.) 

vsname This is the name of a particular volume set. Volume sets may have names 

like vsl, vs2, and vs3 or sys_volset, user_volset, and 
temp_volset, or anything else. 

pathname The pathname that follows the volume set name traces the directories from 

the top directory of the volume set to the specified object. It uniquely 
identifies the object in the volume set. 

For example, if us r is the name of a volume set, then the canonical pathname of the file 
~ jane/books/ ssg might be 

/// sof t ware/doc/ vs/usr/ jane /books/ssg 

Note that this pathname does not specify the node on which the volume set us r is currently 
moimted. This pathname continues to be valid even if the volume set is moved to another node 
in the distributed system, as long as it remains in the same naming domain. 

The canonical form is not the only way to refer to an object in the distributed system, espe- 
cially if the object is in your naming domain. Here are some other valid ways of building 
pathnames: 
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• / / / org /dom/ home / username/ pathname 

This pathname identifies the object relative to the home directory of the specified user. For 
example, if /usr / jane is the home directory of user jane, the following fiill pathnames 
refer to the same object: 

///software/doc/home/ jane/books/ ssg 
// /software/doc/vs /usr/ jane/books/ ssg 

• // /org /dom/ r\o(ie/nodename/ pathname 

This full pathname identifies the object according to the node to which it is attached. For 
example, if the volume set usr in the example is attached to the node named greedo, the 
following full pathname names the same object as the one in the previous example: 

///software/doc/node/greedo/usr/ jane/books /ssg 

ill-1.2.1 A Node's Default Directories 

The following directories are installed by the system in a node's / sy s directory, thereby 
presenting a common set of directories at all BiiN™ nodes: 

aid An alias to the attribute ID directory on the system volume set 

de V An alias to the device directory on the system volume set. 

home An active-only directory that provides access to the home Qearinghouse 

environment of the node's naming domain (see CH_Client in the 
BUN™ I OS Reference Manual). References of type / home /jerry resolve 
to an AD for the home directory of ID jerry. 

id An active-only directory that provides access to the ID Qearinghouse en- 

vironment of the node's naming domain. 

node An active-only directory that provides access to the node Qearinghouse 

environment of the node's naming domain. A listing of "/node" lists the 
names of all the nodes belonging to the node's naming domain. 

rid An alias to the resource ID directory on the system volume set. 

s so An alias to the SSO directory on the system volume set (contains Schedul- 

ing Service Objects). 

s y s An alias to the root directory of the node 's system volume set. 

tdo An alias to the TDO directory on the system volume set (contains Type 

Definition Objects). 

vs An active-only directory that provides access to the vs Qearinghouse en- 

vironment of the node's home naming domain. 

In addition to these root directory entries, BiiN /UX reserves the following entries: 

/bin /etc /usr /tmp 

III-1.3 Directory Operations 

III-1.3.1 Retrieving Entries 

The most common directory call is Directory_Mgt . Retrieve. Retrieve takes a 
name such as /usr / j oe as a parameter and returns an AD for the object stored under the 
specified name. 
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Storing an object's AD by name in a directory does not necessarily mean the object itself is 
also stored there. Directory names can reference objects stored in active memory or in passive 
store. 

(Storing of objects in directories is distinct from the filing service^ which stores data in tradi- 
tional file structures. See Chapter III-3 for information about storing objects.) 

III-1.3.2 Listing a Directory 

To list the contents of a directory, you open it as a read-only device to be read with 
Byte_Str eam_AM or Record_AM. The result is a stream of entry names in ASCII collat- 
ing sequence. Associated ADs are not read. 

In contrast to Byte_Stream_AM or Record_AM, the Open calls in Directory_Mgt 
allow 3i pattern to be specified that is used to filter the stream of names. Only those entry 
names in the directory that match the pattern win be read. A pattern is a combination of plain 
characters which simply match the identical characters in a name, snd pattern operators each 
of which matches a sequence of zero or more characters in a name. 

The pattern operators are: 

? Matches any single character. 

* Matches zero or more characters. 

[amz] Where amz denotes zero or more characters. Matches any of the single 

characters within brackets. 

[a-z] Where a and z are single characters. Matches aU ASCII characters >= a 

and <= z. Match always fails ifz<a. 

\ Escape character. Interprets the following character literally and not as a 

pattern operator. Must precede any of ? , *, [, ] that are to be 
matched. 

! Not (negation). Makes sure the character immediately following does 

NOT match. For example, a [ ! b ] c matches every 3-character string 
beginning with a and ending with c, except the string abc. 

Direct or y_Mgt in the BUN™/ OS Reference Manual lists which access method calls are 
supported and the exceptions that can be raised. 

III-1.3.3 Process Globals and Directories 

TM 

hi the BiiN system, every process has process globals that determine the environment in 
which the process executes. 

Process globals carry the following items pertinent to directories: 

home directory Location after successful login, that is, initial current directory. Set by a 
system administrator. 

current directory Current location in a directory structure and usual starting directory for 
evaluating relative pathnames. 

command name space 

Default directory list to search for commands during name evaluations 
started, for instance, by Human Interface Services. 
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authority list Default authority list, to protect objects for which ADs are being stored 

with a name for the first time, when the directory in which the ADs are 
being stored has no default authority list. 

111-1.3.4 Directory Operations and Transactions 

These calls automatically participate in the caller's transaction: 

Create_directory 

Delete 

Get_name 

Open_directory_by_name 

Rename 

Retrieve 

Store 

If there is no caller's transaction, Create_directory, Rename, and Delete start their 
own transactions. 

Directory_Mgt calls are atomic; when carried out within a transaction, if the transaction 
aborts their effects are undone, whether or not the directory call has already successfully com- 
pleted. 

TM 

The Direct ory_Mgt package description in the BUN /OS Reference Manual describes 
transaction locking. 

III-1.3.5 Standalone Directories 

A normal directory is integrated into the system's directory structure. Occasionally, however, 
it's useful to create directories that are independent of the system's directory structure. 
Standalone__Directory_Mgt creates such directories. The entries in a standalone direc- 
tory are managed with normal Direct or y_Mgt calls. 

Standalone directories differ from normal directories in several important ways: 

• Normal directories have names, whereas standalone directories are identified only by their 
ADs (that is, they do not have names). 

• Normal directories are created and passivated in an existing parent directory. Standalone 
directories are created in the active space; it is the caller's responsibility to passivate the 
standalone before using it. The caUer must update the standalone before tr/ing to use it; 
failure to do so will raise an exception during calls on the standalone. 

• A normal directory resides on the same volume set as its parent directory; a standalone 
directory's home volume set depends on where the caller passivates the standalone's master 
AD. 

• Entries in a normal directory are always protected by an authority list. By default, stan- 
dalones also protect their entries with an authority list; however, if a standalone is created 
with the no_authority parameter set to true, the entries in the standalone are not 
proteaed by an authority list 

Once a standalone is created, the user cannot later add or remove the protecting authority 
list (An existing list can be replaced.) 

• In normal directories, ownership of the directory is assigned to whomever makes the 

Cr e at e_di r e ct or y call. Similarly, by default, ownership of a standalone directory is 
assigned to whomever first passivates the directory. That is, ownership is assigned to tiie 
user_ID of the calling process. 
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It is possible to create nonnal directories in standalones. As with normal directories, the caller 
can also invoke Directory_Mgt calls on entries within this structure. 

For example, a caller may wish to define a database with two components: a database descrip- 
tion and a set of associated ADs to components of the database. One approach would be to 
define the database using two ADs, one to the descriptor, one to a standalone directory contain- 
ing the related AD set. In a simplified scenario, the caller would act as follows: 

1. Create the database and database descriptor. 

2. CaU Create_standalone_directory to create a standalone in the active space (this 
operation does not store and update the standalone directory). 

3. Copy ADs for the descriptor and standalone ADs into the database. 

4. Call Pas sive_Store_Mgt . Update to passivate the database and its embedded objects 
(that is, the descriptor and standalone). 

5. The caUer may create and store entries in the standalone, and perform other calls common 
to directories. 

A standalone directory can be deleted fiom the system by calling 
Passive_Store_Mgt . Destroy, which will destroy the standalone directory and any 
entries it contains. A standalone may also be deleted implicitly as a result of master AD 
deletion, for instance, by deleting an object that contains the standalone's master AD. 

To prevent unwanted deletion of standalone directory entries, the caller might call Destroy 
fi'om a utility that asks the user for confirmation before completing destructive operations. 

IIM .4 Summary 

• Directories associate names with objects by storing <name, AD> pairs in the directory. 

• D ir ector y_Mgt . Ret r ie ve is an important call to obtain an AD for an object in the 
BiiN™ direaory structure. 

• Directory entry names can be listed using Byte_Stream_AM or Record_AM. 

• When listing directory contents, the names can be "filtered" so that only names that match a 
pattern are listed. 

• Directories can be set up with hierarchies, subdirectories, and aliases to other directories, 
across the entire distributed system (crossing node boimdaries). 
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• TM 

Directories allow you to name and organize objects in a BuN system. You can name an 
object by associating a name with the object's AD and storing the <name, AD> pair in the 
directory (Figure III-2-1). Given a name, you can then find any object in the system. This 
chapter gives some specific techniques for using directories. 

Packages Used: 

Directory_Mgt Manages directories and directory entries. 



directory 




Name 


schedule 


AD 





Figure 111-2-1. Directories Contain <Name, AD> Pairs. 



After reading this chapter, you will be able to: 

• Create a directory 

• Store a directory entry 

• Retrieve a directory entry 

• Delete a directory entry 

• List a directory 

• Use a pattern to filter a directory listing 

• Retrieve a directory fix)m process globals. 

Complete listings of the following examples can be found in Appendix X-A. 



III-2.1 Creating a Directory 



The simplest way to create a directory is to call DirectoryJMgt . Create_directory, 
specifying the pathname of the new directory and using defaults for the rest of the parameters. 
The pathname must be a System_Def s . text record. 

Calls Used: 

Directory_Mgt . Create_directory 
Creates a directory. 
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The following example from procedure Great e_directory_coitimand_ex creates a new 
directory with the name given as input. This excerpt shows just the declarations and state- 
ments to create the directory: 

45 dir_name: System_Def s. text (252) ; 

4 6 — Name of the directory to be created. 

47 

48 dir_AD: Directory_Mgt. direct ory_AD; 

4 9 — Newly created directory's AD; returned 

50 — but not used by "create. directory" . 

60 Command_Handler .Get_string{ 

61 cmd_odo => opened_command, 

62 arg_nuniber => 1, 

63 arg_value => dir_name); 

72 dir_AD := Directory_Mgt .Create_directory { 

73 name => dir_name) ; 

The Create_directory call automatically: 

• Stores a master AD for the new directory in the parent directory. 

• Creates a representation of the new directory in passive store. 

• Assigns an authority list to protect the new directory, either the parent directory's default 
authority Ust or the default authority list in process globals. 

• Sets the owner of the new directory to the caller's ID. 

• Returns the new directory's AD to the caller with all type rights. 

You then have a new directory ready for use. 



III-2.2 Storing an AD in a Directory 



The simplest way to create a directory entry is to call Directory_Mgt . Store, specifying 
the new pathname and the object's AD, and using defaults for the other parameters. 

Calls Used: 

Directory_Mgt . Store 

Creates a new directory entry: AD and name. 



The calling process must have store rights in the parent directory for the caU to succeed. The 
calling process will have store rights if the calling process: 

• Created the target directory 

• Has become its owner, or 

• Is granted store rights by the authority list protecting the parent directory. 

Directory_Mgt . Store cannot overwrite an existing entry. 
If the AD is the first AD stored in passive store for the object, then: 

• The directory entry is the object's master AD, 
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• The caller's ID is the object's owner, 

• Either the parent directory's authority list or the process globals authority list protects the 
object, if the authority list parameter is defaulted. 

If there are subsequent stores of the same AD under different names, the subsequent entries are 
alias entries and the object's owner remains the master AD's owner. 

Note that storing the AD for the object does not store the object itself. To update the object's 
passive version, you must caU Passive_Store_Mgt . Request_update after 
Directory__Mgt . Store. 

The following example from procedure Named_copy_ex stores an AD in a new directory 
entry: 

9 source: System_Defs.text; 
10 dest: System_Defs.text) 

62 source_AD := Directory_Mgt .Retrieve (source) ; 

63 dest_AD :== Passive_Store_Mgt . 

64 Create_copy_stub (source_AD) ; 

65 Directory_Mgt .Store (name => dest, 

66 object => dest_AD); 



lli-2.3 Retrieving a Directory Entry 
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Retrieving a directory entry is a common way to obtain an AD for a named object in the BiiN 
system. To retrieve a directory entry, use Directory_Mgt . Retrieve. Retrieve ac 
cepts a name (and optional directory and ID) and returns an AD for a directory entry. 

Calls Used: 

Directory_Mgt . Retrieve 

Returns AD associated with pathname. 



The following excerpt from the Make_ob ject_public_ex example procedure retrieves an 
ADforthelDworld. 

43 — Get the world ID AD 

44 world_name: constant System_Defs.text (9) := 

45 (9, 9, "/id/world"); 

4 6 world_untyped: constant System. untyped_word := 
4 7 Directory_Mgt .Retrieve (world_name) ; 

III-2.4 Deleting a Directory Entry 

To delete a directory entry, use Directory_Mgt . Delete, giving the pathname and using 
the defaults for the other parameters. 

The calling process must have list and store rights in the parent directory for a Delete to 
succeed. 

If the AD is the object's master AD (the first AD stored in passive store) and no alias entries 
exist for this object on the same volume set, then deleting the AD deletes the object's passive 
version. 
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If the AD is the master AD and alias entries do exist on the same volume set, then the OS 
converts one of the alias entries to the master AD, and the object's passive version is not 
deleted. 



III-2.5 Listing a Directory 

To list the contents of a directory, open the directory as a device and use Byte_Str eam_AM 
or Record_AM to read the opened device. The result is a list of entry names. 

Remember that ADs are Retrieved; names are Read. 

Calls Used: 

Directory_Mgt . Open_directory 

Given a directory AD, opens directory for sequential reads. 

Byte__Stream_Am.Ops .Read 

Reads bytes from opened device. 

Byte_Stream_Am.Ops .Write 

Writes bytes to opened device. 

Byte_Stream_AM . Ops . Close 

Qoses an opened device. 



The following example from the List_current_directory_citid_ex example proce^ 
dure uses the following steps: 

1 . Opens directory as an input device. 

2. Opens standard output. 

3. Sets up a buffer. 

4. Sets up a read/write loop: reads bytes from directory into buffer, writes from buffer to 
standard output. 
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11 procedure List_current_directory_cmd_ex 
12 

13 — Function: 

14 — Lists names of entries in user's current 

15 — directory. 
16 

17 — Each entry name is written to the user's 

18 — standard output, on a separate line. 

37 is 

60 opened_dir: Device_Defs.opened_device; 

61 — Opened device for reading stream of names 

62 — from user's current directory. 
63 

64 standard_output : Device_Defs .opened_device := 

65 Device_Defs.opened_device ( 

66 Process_Mgt .Get_process_globals_entry ( 

67 Process_Mgt_Types .standard_output) ) 

68 — User's standard output. 
69 

70 name_buffer: arrayd .. 250) of character; 

71 — Each entry name is read into this buffer 

72 — and then written from it . 
73 

74 length: System. ordinal; 

75 — Length in bytes (characters) of last 

76 — entry name read. 

79 begin 

92 — Open directory for reading, filtered by 

93 — ••: pattern": 
94 

95 opened_dir := Directory_Mgt .Open_directory ( 

96 dir => Directory_AD_f rom_untyped_word { 

97 Process_Mgt .Get_process_globals_entry { 

98 Process_Mgt_Types .current_dir) ) , 

99 pattern => pattern) ; 
100 

101 

102 — Get and write each entry name: 

103 

104 loop 

105 

106 length := Byte_St ream_AM. Ops. Read { 

107 opened_dev => opened_dir, 

108 buffer_VA => name_buffer' address, 

109 length => name_buffer' size/8) ; 
110 

111 Byte_Stream_AM.Ops.Write{ 

112 opened_dev => standard_output , 

113 buffer_VA => name_buffer' address, 

114 length => length); 
115 

116 end loop; 

117 

118 exception 

119 

120 when Device_Def s.end_of_f ile => 

121 

122 Byte_Stream_AM.Ops. Close (opened_dir) ; 

123 

124 RETURN; 

125 

126 end List current directory cmd ex; 
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III-2.6 Using a Pattern to Filter a Directory Listing 

To filter a directory listing according to a pattern, use Directory_Mgt . Open or 
Directory_Mgt . Open_directory_by_name. When you specify a pattern to these 
caUs, only the directory entries that match the pattern are returned by Reads. 

For example, you could add a pattern specification to the call Open_directory. The 
pattern must be a text record conforming to System_Def s . text. The following ex- 
ample from List_current_directory_cmd_ex "filters out" those entries beginning 
witii a period (those that match pattern ! . *): 

27 — *D* define. argument pattern \ 

28 — *D* :type = string 

29 — *D* set .lexical_class syinbolic_name 

30 — *D* set .maximum_length 252 

31 — *D* set.value_ciefault "*" 

32 — *D* end 

54 pattern: System_Defs. text (252) := (252, 252, (others => ' ')); 

55 — Optional "rpattern" used to select entries 

56 — matching the pattern, such as "abc?" or 

57 — "m*device". Default is "!.*", meaning all 

58 — entries NOT beginning with a "." (period). 

92 — Open directory for reading, filtered by 

93 — ": pattern": 
94 

95 opened_dir := Directory_Mgt .Open_directory ( 

96 dir => Directory_AD_f rom_untyped_word ( 

97 Process_Mgt .Get_process_globals_entry ( 

98 Process_Mgt_Types .current_dir) ) , 

99 pattern => pattern) ; 
100 



III-2.7 Retrieving a Directory from Process Globals 

The call Process_Mgt . Get_process_globals_entry allows you to retrieve one of 
the two directory ADs in the process's process globals. A process's globals contain the ADs 
for two directories: the home directory of the process's user_lD and the current directory. 

Calls Used: 

Process_Mgt . Get_process_globals_entry 

Retrieves a value from a slot in process globals. 

Directory_Mgt . Get_name 

Gets the fuU pathname of an object's master AD. 



The following example from Show_current_directory_cmd_ex retrieves the name of 
the current directory from process globals with the following calls: 

1. Process_Mgt . Get_process_globals_entry gets the AD for the current direc- 
tory. 

2. Direct or y_Mgt . Get_name gets the name associated with the AD of the current direc- 
tory. 
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10 procedure Show_current_directory_cmd_ex 

29 is 

37 current_dir: Directory_Mgt.directory_AD := 

38 Directory_Mgt .directory_AD{ 

39 Process_Mgt .Get_process_globals_entry { 

40 Process_Mgt_Types .current_dir) ) ; 

41 — Current directory's AD. 
42 

43 current_dir_untyped : System. untyped_word; 

44 FOR current_dir_untyped USE AT 

45 current_dir' address; 

4 6 — Current directory's AD as an untyped word, 

47 

48 dir_name: Sy stem_Defs. text (252) ; 

4 9 — Current directory's name. 

51 begin 

52 

53 — Get current directory' s pathname : 

54 

55 Directory_Mgt .Get_name ( 

56 obj => current_dir_untyped, 

57 name => dir_name) ; 

73 end Show current directory cmd ex; 
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This chapter shows you how to protect stored objects from unauthorized access, using IDs and 
authority lists. 

Packages Used: 

Identification_Mgt 

Provides operations to manage IDs and ID lists. 

Author it y_List_Mgt 

Provides calls to manage authority lists and to evaluate a caller's access 
rights to objects protected by authority lists. 

Us er_Mgt Provides calls to manage a user's protection set and user profile. 



Objects may be protected with authority lists and IDs. 

An authority list shows which IDs can access the object, with what access rights. An ID 
identifies what agent is trying to access the object. A process carries IDs for agents it may 
represent in an id list (Figure III-3-1). 
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Figure III-3-1. A Caller Accesses a Protected Object 



In Figure III-3-1, the caUer carries IDs for joe, finance, design_team and world. 
When this caller tries to access an object, all these IDs are used in evaluating the caller's 
access to the object. (Evaluation is discussed in more detail later in this chapter.) 

The object itself is protected by an authority list. In the authority list, ID fred has all rights, 
ID susan has "use" rights, ID finance has "use" and "modify" rights, and ID world has 
no rights. When a caller tries to access this object, these <ID, type rights> pairs are used in 
evaluating the caller's access to the object. 
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III-3.1 Concepts 

The following concepts present authority-list-based protection from a user standpoint 

III-3.1.1 Why Objects Need Authority-Based Protection 

When you store an object, you must protect it with authority-based protection. This is distinct 
from the address space protection mechanism provided by ADs. Basically, authority lists are 
intended to extend the architecture's capability-based protection (ADs) into passive store. 

An object is stored in passive store similar to the way files are stored in a conventional filing 
system. If there were no authority-list protection, the object would be accessible to any user 

TM 

over an entire distnbuted BiiN system, not just to the caller who stored the object. This 
presents a problem: how can the object itself be protected from unauthorized access while in 
passive store, which is accessible from the entire distributed system? Authority lists provide a 
solution. 

You associate the object with an authority list. To oversimplify, the authority list specifies 
exactly which IDs, with what type rights, can access the object. Thereafter, any caller's ID 
must appear in the authority list, with the proper type rights, for the caller to access the object. 
(Evaluation is discussed in fiiU in Section III-3.1.6). 

III-3.1.2 IDs Identify the Caller 

An ID represents an entity, either an individual or an access class. An individual is usually a 
user (joe). An access class may represent a collection of users (des ign_gr oup), a 
program (database) or all "outsiders" (world). 

Typically, each individual has a unique ID, which is created by the system administrator when 
creating a new user. The system administrator may also define various access classes within 
the system and create IDs for them, so that users, by holding an ID to one or more access 
classes, may also portray themselves as members of these classes. 

The caller carries IDs in an /D list which is stored in the caller's process globals. The first ID 
in the list is the caller's user ID. The ID list can contain one or more IDs. For example, in 
addition to the caller's user ID, a single caller might carry IDs for the following: 

another user (joe) 

a group of users (des ign_t earn) 

a program (db_data_entry) 

a group of programs (cad_system) 

a generic ID (wo rid) 

To access an object, one of a caller's IDs must match an ID in the object's authority list, with 
the proper rights. Access to the object is evaluated according to the rights associated with that 
ID in the authority list (This is oversimplified; more on evaluation in Section III-3.1.6). 

In addition to the IDs in the caller's process globals, many Directory_Mgt caUs accept an 
explicit ID. This is especially useftil for system utilities tiiat may require rights for an ID that 
is not available in the ID list itself. 
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m-3.1.2.1 What's In an ID? 

Figure III-3-2 shows the parts of an ID. 
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Figure in-3-2. Parts of an ID 



User (logon) name Name for this ID. 

Protection set A protection set protects an ID just as an authority list protects a stored 
object. IDs are protected with protection sets instead of authority lists 
because IDs are maintained in the Qearinghouse, not in passive store. In 
Figure ni-3-2, the protection set for ll> joe allows all type rights to callers 
joe and admin. 

Password Password for this ID. Originally set by the system administrator, and 

changeable by anyone with control rights to the ID. 

User profile Originally set by the system administrator, and some parts changeable by 

anyone with control rights to the ID. 

IDs and ID lists are active-memory-only objects, maintained through 

Identif ication_Mgt and the Qearinghouse. Thus, calls to Passive_Store_Mgt on 

IDs and ID lists will raise exceptions. 

IDs are created with the Identif ication_Admin package. 



III-3.1.3 A Process's ID List 



The caller's ID list is in the caUer's process globals. By convention, the OS always interprets 
the first ID in a process's ID list as the user ID. (By default, the second ID in the list is the 
group ID for BiiN™AJX applications.) BiiN^lUX User's Guide). See Figure III-3-3 for an 
illustration of an ID list 

Any caller can obtain an AD to its ID list with Process_Mgt 

. Get_j5rocess_globals_entry or can list the contents of an ID list with 

Identif ication_Mgt . List_IDs, but setting the ID list in the process globals can only 

be done using the P r o ce s s_Admin or Job_Admin packages. 

The caller's ID hst is inherited by child processes, just as other items in process globals are 
inherited. 
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Figure in-3-3. A Process's ID List 



III-3.1.4 Type Rights on an ID 

The following type rights are defined for IDs: 

Portray rights Needed to enter an ID into a process's ID list 

Control rights Needed to change an ID's password or to set an object's owner. The user 
ID in a process's ID list must also have control rights. 

By default, users have portray and control rights to their own user IDs. 

Portray rights are acquired by being passed an ID AD with such rights, or through rights 
evaluation. ID rights can be amplified to control and portray rights by providing the correct 
password to Identif ication_Mgt . Portray_ID. 

III-3.1.5 Authority Lists Specify Who Can Access Objects 

An authority list is composed of a. protection set, a record containing <ID, type rights mask> 
pairs. Normally, the caller who stores an object assigns the authority list, either specifying one 
or using the default. 

An authority list is an object in itself, separate from the object it protects. As objects, authority 
lists need to be stored using Directory_Mgt and updated using Passive_Store_Mgt; 
these calls arc not done automatically. 

Both active and stored objects can be protected by authority lists, and any number of objects 
can share a single authority list, thus saving storage space (Figure III-3-4). 
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Figure in-3-4. Multiple Objects Sharing an Authority List 

III-3.1.6 How a Caller's Access Rights to an Object Are Evaluated 

Whenever a caller retrieves or activates an AD, the caUer's access rights to that object are 
evaluated. That is, the caller's IDs are checked against the authority list, to return the proper 
type rights on the underlying object. 

Directory_Mgt .Retrieve does an implicit Author it y_List_Mgt .Evaluate 
against retrieved ADs before returning the result to the caller. 

Object activation, which is done transparently by P a s s i ve_S t o r e_Mgt , also does an 
Evaluate; however, evaluation differs somewhat between a Retrieve and activation. The 
following sections discuss each evaluation process. 

in-3.1.6.1 Evaluating Access During a Retrieve 

Figure III-3-5 shows the steps in the evaluation during a Directory_Mgt . Retrieve. 
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Figure III-3-5. Evaluating Access During a Retrieve 



1. If the object has an authority list, proceed to step 2. Otherwise, activate the object, granting 
the same type rights as when the object was stored, and end evaluation. 

2. If at least one of the caller's IDs matches an ID in the object's authority list, evaluation 
continues at step 4. If the caller's IDs do not match any in the authority list, evaluation 
proceeds to step 3. 

3. If the caUer is the object's owner or volume set administrator, the caUer receives an AD 
with no type rights (no authority list access) and evaluation ends. If the caller is not the 
object's owner or volume set administrator, the caller gets the exception 
Directory_Mgt . no_access and evaluation ends. 

4. The type rights associated with the matching IDs in the authority list are combined (logical 
OR). This results in the maximum type rights for that caller and that authority list. 

5. The maximum type rights are then compared (ANDed) with the type rights in the object's 
master AD. This results in the least type rights for that caller and that object. That is, the 
caUer can never get more rights than are present in the object's master AD. 

6. The caller receives an AD with the final evaluated type rights. 
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For example, consider the caller, object, and authority list in Figure III-3-6. 
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Figure in-3-6. Example: Evaluating Access During a Retrieve 

1 . The caller's IDs design jeam and world match IDs in the object's authority list 

2. Type rights associated with ID designjeam are "use" and "modify". Type rights associated 
with ID world are "use". A logical OR between these two results in type rights "use" and 
"modify". 

3. The type rights in the object's master ID are "use" only. A logical AND between these 
rights, and the results of the OR operation gives "use" rights only. 

4. The caller receives an AD for the object with "use" rights. 

in-3.1.6.2 Evaluating Access Rights During Activation 

A caller's access to an object is also evaluated when activating the object's AD. If access is 
not granted, a null AD is activated in place of the AD that should be activated, instead of 
raising Directory_Mgt . no_access . See the Passive_Store_Mgt package for 
more information about AD activation. 



ill-3.2 Techniques 

After reading this section, you wiU be able to: 

• Get information about an object's protection 

• Use default protection 

• Create an authority list 
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• Change a directory's default authority list 

• Change an object's owner and authority list. 

Creating IDs is a privileged operation for the system administrator, see the BiiN^ Systems 
Administrator's Guide. 

III-3.2.1 Getting Information about an Object's Protection 

The following calls are used to get information about an object's ID and authority lists. 

Calls Used: 

Identif ication_Mgt . Get_ob ject_owner 

Returns the owner ID AD of the object. 

Author it y_List_Mgt . Get_ob ject_authority 

Returns AD for the object's authority list 

Author it y_List_Mgt . List_authority 

Returns the set of authority list entries. 

Directory_Mgt . Get_def ault_authority 

Retrieves directory's default authority list. 

Authority_List_Mgt . Evaluate 

Returns type rights on object. 

Identif ication_Mgt . List_IDs 

Returns the set of IDs from the ID list. 



Note that the calls List_authority and List_IDs require the caUer to receive results in 
an out variable. 

III-3.2.2 Using Default Protection 

Normally, what happens by default is all the protection you need. The usual way to store an 
object with authority list protection is to use Directory_Mgt . Store, accepting the target 
directory's default authority list as the object's protecting authority list. 

III-3.2.3 Creating an Autliority List 

In general, to avoid unexpected results, an authority list should be stored and updated before 
being assigned to protect objects. 

Calls Used: 

Author it y_List_Mgt . Create_authority 
Creates an authority list 



To create an authority list: 

1. Create a protection set Gist of <ID, type rights> pairs) in the form required by 

User Mgt .protection set. 
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2. Create the new authority list with Create_authority, specifying the protection set. 
You will receive an AD, with control rights, to the new authority list. 

3. Store the new authority list AD with Directory_Mgt . Store. 

4. Passivate the new authority list with Pas sive_Store_Mgt . Request_Updat e. 

The following example from Make_ob j ect__public_ex shows how to create a simple 
authority list for an object, allowing all type rights for the world ID. 

10 procedure Make_object^ublic_ex( 
42 is 

51 — Define the protection set 

52 entries: constant User_Mgt .protect ion_set (1) := ( 

53 size => 1, length => 1, 

54 entries => (1 => (rights => (true, true, true), 

55 id => world_id) )) ; 
56 

57 — Create the authority list 

58 aut_list: constant 

59 Authority_List_Mgt.authority_list_AD := 

60 Authority_List_Mgt .Create_authority (entries) ; 

61 aut_untyped: System. untyped_word; 

62 FOR aut_untyped USE AT aut_list' address; 
63 

64 begin 

67 Directory_Mgt .Store (aut_list_path, aut_untyped) ; 

68 Passive_Store_Mgt .Request_update (aut_untyped) ; 

78 end Make_ob ject_public_ex; 

Once the authority list has been created, stored, and updated, you can then associate that list 
with any object. 

III-3.2.4 Changing a Directory's Default Authority List 

You may want to change a directory's default authority list to another authority list. Note that 
Directory_Mgt . Create_directory sets the default authority list to null; the caller 
must act to set a directory's default authority hst. 

Calls Used: 

Directory_Mgt . Set_def ault_authority 

Sets directory's default authority list 



A directory's default authority list is the first one Store looks for when a master AD is stored 
with default protectioa 

The default authority list of a directory is not necessarily the authority list that protects the 
directory itself. 

III-3.2.5 Changing an Object's Owner and Authority List 
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Calls Used: 

Identif ication_Mgt .Portray_ID 

Returns ID AD with control and portray rights. 

Identif ication_Mgt . Set_ob ject_owner 

Sets or changes the owner ID of an object. 

Author it y_List_Mgt . Set_ob ject_authority 

Associates a new authority list with an object. 



To change an object's owner. 

1. Obtain the new owner ID AD with Directory_Mgt . Retrieve. 

2. Obtain control rights to the new owner ID with Identif ication_Mgt . Portray_lD. 

3. Replace the object's current owner with a new owner with Set_object_owner. The 
caller's ID (either passed or default user ID) must match the old owner ID, and must have 
control rights. By default, Set_ob ject_owner uses the caller's user ID, which has 
control rights. 

To change an object's authority hst: 

1. Replace the object's authority list with a new authority list via 

Set_ob ject_author ity. The caller's ID (either passed or default user ID) must 

match the owner ID, and must have portray rights. By default, 

Set_ob ject_authority uses the caller's user ID, which has portray rights. 

III-3.3 Summary 

• Objects may be protected with authority lists and IDs. 

• An authority list shows which IDs can access the object, and what type rights they can 
acquire. 

• An ID identifies what caller is trying to access the object. 

• A caller carries one or more IDs in an ID list which is stored in the caller's process globals. 
The first ID in the ID list is the caller's user ID. 

• A protection set protects an ID just as an authority list protects a stored object. 

• Whenever a caUer retrieves or activates an AD, the caller's access to that object is 
evaluated. 

• During a Retrieve, the caller's IDs are compared with the object's authority Ust and 
master AD to return the proper rights on the retrieved AD. 

• During AD activation by Pass ive_Store_Mgt, the "containing" object's owner ID is 
compared with the object's authority list to return the proper rights on the activated AD. 
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A name space is a list of directories to be searched when looking for an object. This is similar 
in function to the UNIX-like path environment variable or the MS-DOS PATH command. 
This chapter gives concepts and techniques for creating a name space. 

Packages Used: 

Name_Spa ce__Mgt 

Provides caUs to manage name spaces Gists of directories). 
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Figure in-4-1. A Name Space Lists Directories to be Searched 



III-4.1 Concepts 

A name space contains a string list Each string list is the name of a directory. 

III-4.1.1 A Name Space is a List of Directories 

Directories in a name space are searched in the order in which they appear. For example, in 
Figure III-4-1, Directory_Mgt first looks in directory /bin, then in directory 
/local /bin, then in directory /usr/bin. If the "current directory", represented by dot (.), 
is in the name space, the directory that is current at the time the call is made wiU be searched. 

Each user's user profile references a command name space, used by Q.EX when searching for 
commands. 

The directories in the name space are used only for retrieving and listing. That is, no 
Store/Delete/Rename or other Direct ory_Mgt calls are allowed on the listed direc- 
tories. 
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Opening a name space does not open any directories in the name space. Instead, directories 
are opened as encountered during Reads. Thus, the first directory in the name space is 
opened at the beginning of the first Read request. Rights evaluation is performed against 
listed directories when they are opened, to make sure list rights are present in the directories. 

As name space Reads progress, the current opened directory is closed and the next directory 
in the name space is opened. When the last directory in the list reaches end_of_f ile, the 
name space is also marked as at end_of_f ile. 

A pattern may be specified to select only names which satisfy the pattern (see Chapter in-2 for 
an example of using a pattern). 

Name spaces are constants and cannot be modified once they have been created. 
III-4.1.2 How a Name Space References Directories 

Reads on name spaces return names (not ADs), just like Reads on directories. 

When read using Byte_Stream_AM Reads, the names are separated by an ASCII newline 
character, for Record_AM Reads, each name is returned as a record. 

Note that if a directory's pathname is renamed after the name space is created, the directory 
cannot be opened in the name space because the name space won't be able to find it. 

Relative pathnames are usually avoided in name spaces, because you want to use the same 
name space regardless of your starting directory. An exception to this is the current directory 
(.) which is often the first element in a name space. 

Reads on name spaces do not participate in transactions and the directory currently being read 
is not locked. 



III-4.2 Techniques 

After reading this section, you wiU be able to: 

• Create a name space 

• Change the command name space in the user profile 

• Change the command name space in process globals. 

lli-4.2.1 Creating a Name Space 

To create a name space, use Name_Space_Mgt . Great e_name_space, specifying the 
list of directories. The list must conform to System_Def s . string_list. 

Calls Used: 

Name_Space_Mgt . Create_name_space 

Creates a name space containing text entries. 



The following is from the example Create_name_space_cmd_ex in Appendix X-A. The 
developer uses the Command_Handler package to get the new name space's name and 
parent directory from user input. 

Using Name Spaces 111-4-3 



f JK.JC:<JUAiVll.i^/\.I\. X 



17 procedure Great e_name_space_cmd_ex 
78 is 

86 directory_list: System_Defs.string_list (508) ; 

87 — String list containing pathnames of the 

88 — directories in the new name space. 

143 Command_Handler .Get_string_list (opened_cmd, 2, 

144 arg_value => directory_list) ; 

210 name_space := Name_Space_Mgt . Great e_name_space ( 

211 directory_list) ; 

221 Directory_Mgt .Store (name, name_space_untyped) ; 

337 Passive_Store_Mgt .Request_update ( 

338 name_space_untyped) ; 

358 end Greate_name_space_cmd_ex; 

lli-4.3 Changing a User's Command Name Space 

To change a user's command name space in the user profile, use User_Mgt: 

1. Use User_Mgt . Get_user_prof ile to get the current user profile record. 

2. Change the coiranandjpath component of the user_jprof ile record to contain the 
desired new command path, of type System_Def s . string_list. 

3. Use Set_user_prof ile with the new user_prof ile record to insert the new com- 
mand name space in the user's profile. 

It is the responsibility of the one modifying a user profile to guarantee the validity of names in 
the profile. 

III-4.4 Changing the Command Name Space within a Job or 
Process 

The call Process_Mgt . Set_process_globals_entry allows you to insert a name 
space into its slot in process globals, to be effective for the duration of the job or process. 

Calls Used: 

Process_Mgt . Set_process_globals_entry 

Assigns a value to a process globals entry. 



Note that as for any object, the name space should be created and passivated before being 
assigned to process globals. 

The following example from Process_Globals_Support_ex shows setting the 
cmd_name_space slot in process globals. 
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492 procedure Set_command_name_space ( 

493 ns : Name_Space_Mgt . name_space_AD ) 
494 

495 — Logic: 

496 — 1. Check that "ns" is a name space. 

497 — 2. Set the new command name space. 

498 is 

4 99 ns_untyped: System.untyped_word; 

500 FOR ns_untyped USE AT 

501 ns' address; 

502 begin 

503 if not Name_Space_Mgt . 

504 Is_name_space {ns_untyped) then 

505 RAISE System_Exceptions.type_mismatch; 
506 

507 else Process_Mgt . Set_process_globals_entry ( 

508 slot => Process_Mgt_Types.cmd_name_space, 

509 value => ns_untyped) ; 

510 end if; 
511 

512 end Set_command_name_space; 

III-4.5 Summary 

• A name space is a list of directories to be searched when looking for an object. 

• Each user's user profile references a command name space, used by CLEX when searching 
for commands. 
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A symbolic link provides a way to associate another name with an object already stored under 
a different name. This chapter gives concepts and techniques for creating a symbolic link. 

Packages Used: 

S ymbol i c__Link__Mgt 

Provides calls to create, list, and identify symbolic links. 



Figure ni-5-1 diagrams a symbolic link. 



'joe/ 



'Sue/ 



name 1 
AD1 



specs 



name 2 


pro], spec 




AD2 








,, symbolic 


link 




~joe/specs 



Retrieve ("~sue/proj.spec") returns AD1 
Figure in-5-1. A Symbolic Link 



III-5.1 Concepts 



A symbolic link contains a pathname. Symbolic link evaluation retrieves whatever AD is 
stored with that pathname. 

If an AD to a symbolic link is stored in a directory entry, then retrieving from the entry does 
not return the entry's AD. Instead, an AD to the object referenced by the link is returned. 

For example, in Figure III-5-1, aDirectory_Mgt .Retrieve ("~sue/proj . spec") 
returns AD 1. 

It is also possible to suppress the link. For example, in Figure III-5-1, you can obtain AD 2 by 
suppressing link evaluation of -sue /pro j . spec. 

III-5.1.1 Suppressing Link Evaluation 

The at sign ( @ ) suppresses link evaluation. 

If Directory_Mgt . Retrieve is called with a pathname that contains an at sign ( @ ), the 
part of the pathname preceding the at sign is evaluated. If the resulting object has the link 
attribute, the link evaluation is suppressed and the AD of the named object itself is used to 
complete the evaluation. 



III-5-2 
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For example, in Figure III-5-1, a Directory_Mgt .Retrieve ("~sue/proj . specQ") 
returns AD 2. 

The one exception to this rule is Directory_Mgt . Delete when the name supplied is the 
name of the link object itself. In this case, whether or not there is a trailing at sign, the link 
object itself is deleted. 

III-5.1.2 How Symbolic Links Compare with Aliases 

Symbolic links and aliases provide two different ways to associate another name with an object 
that already has a name. A symbolic link can be thought of as a "soft link," and an alias as a 
"hardUnk." 

A symbolic link is a new name for a new object that contains the name of an existing object. 

An alias is a new name for an object that already has a name. 

Aliases can become master ADs, whereas symbolic links can't 

A symbolic link has the following advantages: 

• It references an object name. Any object can exist under this name at one time or another. 
This means you can also update an object under that name and not end up with a dangling 
reference as for aliases (you might want to replace an existing program with a revised 
version, or some such). 

• You can set its value to a CL variable, for example $mybin, which gives you a great deal 
of flexibility. 

A symbolic link has the following disadvantages: 

• The symbohc link cannot inherit "mastership" for the object referenced by the link's value. 

• The associated link value is "name" specific, so that if a different object is stored under the 
same name, the user may end up accessing something incompatible with the type needed. 

[11-5.1.3 Symbolic Links and Links in General 

Symbolic links are one implementation of the OS link attribute as defined by Link_Mgt. 
You may also provide your own implementation of the link attribute, so that a 
Direct or y_Mgt . Retrieve will execute your implementation when it retrieves your ob- 
ject with the link attribute. See the Link_Mgt package for information about implementing 
the link attribute. 



III-5.2 Techniques 

After reading this section, you will be able to: 
• Create a symbolic link. 

111-5.2.1 Creating a Symbolic Link 

To create a symbolic link, use Symbolic_Link_Mgt . Great e_synibolic_link, 
specifying the pathname within the link. An AD to the link is returned. 
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Calls Used: 

Symbol ic_Link_Mgt . Create_syinbolic_link 
Creates a symbolic link. 



III-5.3 Summary 



• A symbolic link provides a way to associate a name with an object stored imder a different 
name. 

• Symbolic link evaluation retrieves whatever AD is stored with that pathname, 

• The at sign ( @ ) can suppress link evaluation, to allow you to retrieve the AD of the 
symbolic link. 
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Part IV 

I/O Services 



This part of the BiiN™/OS Guide gives concepts and techniques for managing files, terminals, 
windows, printers, and other devices using byte stream, record, and character display VO. 

The chapters in this part are: 

Understanding I/O Access Methods 

Explains the I/O access methods provided by the OS. An access method is 
a set of operations for accessing devices. 

Using Basic I/O Shows basic byte stream and record I/O techniques. 

Managing Stream Files 

Shows you how to manage stream files. 

Using Windows Explains the use of windows on character and graphics terminals, includ- 
ing terminal manager support for windows and I/O access methods. 

Using Character Display I/O 

Shows you how to do I/O to a character display device. 

Printing Explains spooled and direct printing. 

Understanding Structured Files 

Explains basic filing concepts and trade-offs between the available struc- 
tored file organizations. 

Managing Files and Indexes 

Explains calls and data structures for managing files and indexes. 

Using Record I/O vnth Structured Files 

Explains the concepts and techniques for using record I/O with strucmred 
files. 

Locking Files and Records 

Explains concepts and techniques for locking and unlocking files and 
records. 

Processing Collections of Records 

Explains concepts and techniques for processing collections of records. 

1/0 Services contains the following services and packages: 

basic I/O service: 

By t e_S t re am_AM 

Device_Defs 

S imp 1 e_F i 1 e_Adm i n 

character terminal service: 

Character_Display_AM 

Character_Terminal_Mgt 

Terminal_Admin 

Terminal_Defs 

Terminal_Info 

Window_Services 

print service: 
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P r in t e r_Adm i n 

spool service: 

Spool_Def s 

Spool_Device_Mgt 

Spool_Queue_Admin 

fUing service: 

File_Admin 

Flle_Defs 

Record_AM 

database support service: 

Join_Interface 
Record_Processing_Support 
Sort_Merge_Interface 
Trusted_Record_Processing_Support 

data definition service: 

Data_Definition_Mgt 
DDF_Utility_Support 
Field_Access 

volume set service: 

Volume_Set_Admin 
Vo 1 ume_S e t_D e f s 
VSM_D i s k_Admi n 
VSM_Disk_Support 

basic disk service: 

Basic_Disk_Mgt 

basic streamer service: 

Basic_Streamer_Mgt 

rmU device service: 

Nuldev Mgt 
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This chapter describes the I/O access methods provided by System Services. An access 
method is a set of operations for accessing devices. Applications interact with devices through 
access methods. The I/O access methods provided by the BiiN™ Operating System are: 

Packages Used: 

Byte_Stream_AM 

Provides device-independent I/O using streams of bytes. 

Record_AM Provides device-independent record I/O. 

Character_Display_AM 

Provides device-independent I/O to character display devices such as 
printers, plotters, and windows on character and graphics terminals. 



The BiiN™ programming languages provide their own calls for I/O. You may prefer to use 
them when writing code which must be portable between operating systems. 



IV-1.1 Devices 



A device is an object that supports one or more I/O access methods, and which represents a 
hardware or software system device. Device_Def s . device is the Ada type for ADs to 
devices. 

Devices may be implemented in hardware or software. Device types provided by the BiiN™ 
Operating System include: 

basic disk 

basic streamer 

command input device 

directory 

file 

form 

name space 

pipe 

print device 

report 

window 

Terminals and disks are nomially not accessed directly as devices, but are accessed through 
windows and files, respectively. 



IV-1 .2 Opened Devices 



When a device is opened, an opened device is created. Opened devices are I/O channels to 
devices. Each access method Open call creates a new opened device. 
Device_Def s . opened_device is the Ada type for ADs to opened devices. 

When performing I/O, an application selects an access method and passes a device to be 
opened to its Open call. An opened device representing an I/O chaimel is returned. The 
opened device is then passed as a parameter when making I/O calls on the channel. See Figure 
IV=M. 
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Opened Device 



Representation of 
a physical device 



Process 




Figure IV-1-1. Opened Devices are I/O Channels to Devices 

Zero or more opened devices can be active simultaneously for a given device. Depending on 
the device, subsequent I/O calls may either be restricted to the access method used to open the 
device, or allowed to be finom any supported access method. 

A Close call closes a single opened device. I/O processing with a device is active until all 
opened devices associated with the device are closed. When a job tenninates, any opened 
devices which have not been closed by the application are closed. The access method 
ls_open calls can be used to detennine whether a job's opened devices have been closed. 

Multiple processes, in one or more jobs, can share a single opened device. An opened device 
exists until it is closed by all jobs that reference it. 



IV-1.3 Concurrent Access to Opened Devices 



Asynchronous I/O allows the execution of a process to proceed concurrentiy with the execu- 
tion of I/O operations it has called. A process that opens a device is free to pass the opened 
device to other processes in the same or different jobs. These processes can then make concur- 
rent I/O calls. 

Multiple opened devices can be open concun*entiy on the same device. For example, multiple 
jobs can concurrentiy open and read a file. This increases efficiency and aUows a process the 
option of waiting for the completion of I/O from multiple devices. 

I/O operations are normally performed synchronously. For input calls, however, a process 
may choose not to block, and to wait for the arrival of input after having made an input call. 
Blocking can be avoided or postponed by the Enable_input_notif ication and 
Disable_input_notif ication calls common to all the access methods. These calls 
activate and deactivate asynchronous notification to processes of the arrival of input from an 
opened device. 

A device manager acts as a traffic cop, supervising record locking, serialization of process I/O, 
etc. The application, however, can explicitiy stipulate the degree of concurrency which can be 
exercised with an opened device. Device_Def s . allow_mode, a parameter in access 
method Open calls, defines what concurrent I/O is allowed on an opened device. These 
modes include: 
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readers - Allows only readers to share a device. A process is considered a reader when it 
opens a device for input or input_j5artial. 

anything - Allows other readers or writers to share a device. Synchronization is the 
application's responsibility. 

nothing - Allows no concurrent use of a device. 

Figure IV- 1-2 shows two processes communicating concurrently with the same opened device. 



Process A 



Opened Device 



Representation of 
a physical device 




Figure IV-1-2. Concurrent I/O 



IV-1 .4 Device Independence 



Each access method is supported by multiple devices. See Figure IV- 1-3. This enables an 
application to be independent of any particular device. An access method is a set of operations 
that give a caller a pre-defined I/O charmel to one or more devices. 



IV-14 
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Figure rV-1-3. Access Methods are Supported by Multiple Devices 



BiiN Operating System attributes provide a method for defining general purpose operations 
supported by multiple object types. This method enables type-specific implementations of 
general purpose operations, such as access method calls, to be boxmd to a specific object type, 
such as a device type. Devices with access method attributes can perform VO via a standard 
access method interface. For example, an application may send records to a report device and 
to a file. Both devices contain the record I/O attribute and are able to interpret the data in their 
own way. 

Devices may often be accessible by more than one access method. For example, an application 
caUs the byte stream Open for a device which supports both byte stream and record VO. The 
opened device, although opened with a byte stream I/O call, can be used for making record I/O 
calls. 

Table IV-1-1. Devices and Supported Access Methods 





ACCESS METHOD 


Device 


Byte Stream 


Record 


Char Display 


basic disk 


X 


X 




basic streamer 


X 


X 




command input device 


X 


X 




directory 


X 


X 




file 


X 


X 
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ACCESS METHOD 


Device 


Byte Stream 


Record 


Char Display 


form 




X 




namespace 


X 


X 




pipe 


X 


X 




print device 


X 


X 


X 


report 




X 




window 


X 


X 


X 



IV-1.5 How Access Method Implementations Can Vary 

Devices may be opened in one of the following modes: 

input - Input Read rights required. 

input_partial - Input Read rights required. A file can be opened in this mode even if all 
volumes used by the file are not online. 

output - Output Write rights required. 

incut - Input and output. Read and write rights required. 

The modes in which a device can be opened depend on the type of device. For example, the 
device manager should not allow a printer to be opened in input mode. 

A device manager must implement every operation of the access method being supported, 
although it need not support them. An instance of an access method operation may raise 
System_Exceptions . operation_not_supported. Some operations are common 
to aU access methods. All others are access method-dependent. 



IV-1 .6 BiiN™ Operating System I/O Access Methods 

The byte stream, record, and character display access methods have the following operations in 
common: 



Open_by_name 

Ops.Close 

Ops.Disable_input_notification 

Ops.Enable_input_notification 

Ops.Hush 

Ops.Get_device_info 

Ops.Get_device_object 

Ops.Is_open 

Ops.Open 



Table IV-1-2. Common I/O Operations 



IV- 1-6 
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IV-1.6.1 Byte Stream I/O 



An application should always be able to use byte stream I/O for all devices. (Forms and 
reports are exceptions since they are designed for record data.) Therefore, a device manager is 
expected to provide at least an implementation of the byte stream access method. 
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Figure IV-1-4. Byte Stream I/O 



Table IV- 1-3 lists selected byte stream access method caUs. 



Byte_Stream_AM.Ops.At_end_of_file 
Byte_Stream_AM.Ops.Read 
Byte_Stream_AM.Ops.Set_position 
Byte_Stream_AM.Ops. Write 



Table rV-1-3. Selected Byte Stream Access Method Calls 



IV-1 .7 Record I/O 



Record I/O is used to read and write records. Forms and reports are specifically designed to be 
used with this access method. 

















Process A 


•Ni^ 






J V 




/ / 


Records ^ 




Current 
Record 


Series 


/ / 


If H ^ 


of 
Records 


/ r 


.>■ 


t '/° 


Hi h^ 


/ / 




H 


























Dpened Devic 
Figure IV- 


e 

1-5. Reco 


stream Fil 

rdl/O 


€ 





Records can be accessed in any of four ways: 

Physical sequential 
Physical random 
Indexed sequential 
Indexed random. 



Understanding I/O Access Methods 



IV-1-7 



r M\MliMuM.irx±l.-^tXMX M. 



This access method provides access by index and key, and provides file and record locking. 
Table IV- 1-4 lists selected record access method calls. 



Record_AM.Ops.Delete 

Record_AM.Keyed_Ops.Delete_by_key 

Record_AM.Ops.Get_DDef 

Record_AM.Ops.Insert 

Record_AM.Ops.Lock_all 

Record_AM.Ops.Read 

Record_AM.Keyed_Ops.Read_by_key 

Record_AM.Keyed_Ops.Read_key_value 

Record_AM.Keyed_Ops.Set_key_range 

Record_AM,Ops.Set_open_mode 

Record_AM.Ops.Set_position 

Record_AM.Ops.Unlock_all 

Record_AM.Ops.Update 

Record_AM.Keyed_Ops.Update_by_key 



Table IV-1-4. Selected Record Access Method Calls 



IV-1.8 Character Display I/O 



The character display access method is typically used to access devices with two-dimensional 
display surfaces. 



Process A 



Opened Device 



Process B 




Window A 



Window B 
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Character Terminal 



Opened Device 
Figure IV-1-6. Character Display I/O 
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Character_Display_AM.Ops.aear 

Character_Display_AM.Ops.Qear_to_bottom 

Character_Display_AM.Ops.aear_to_end_of_line 

Character_Display_AM.Ops.Delete_char 

Character_Display_AM.Ops.Delete_line 

Character_Display_AM.Ops.Get_cursor_position 

Character_Display_AM.Ops.Insert_char 

Qiaracter_Display_AM.Ops.Insert_line 

Character_Display_AM.Ops.Move_cursor_absolute 

Character_Display_AM.Ops.Move_cursor_relative 

Character_Display_AM.Ops.Read 

Character_Display_AM.Ops.Ring_bell 

Character_Display_AM.Ops.Set_input_type_mask 

Character_Display_AM.Ops. Write 



Table IV-1-5. Selected Character Display Access Method Calls 



IV-1.9 Standard I/O Connections 

A process normally executes in an environment with four existing 1/0 assignments: 

standard_input 
standard_output 
standard_message 
user_dialog 

These I/O assignments are declared in 

Process_Mgt_Types .process_globals_entry and are retrieved using 
Pr oces s_Mgt. (See the BHN^/OS Reference Manual.) They are part of a caller's default 
environment and are contained in process globals, objects that hold user information about a 
specific process. user_dialog is normally a window which is guaranteed to be an inter- 
active device for situations in which a timely response is needed. 

The information in the process globals for a specific process is available to any user with an 
AD to the process. See Chapter VI-2 for more information on process globals. 



IV-1. 10 Summary 



An access method is a set of operations for accessing devices. Applications interact with 
devices through access methods. 

A device is an object that supports one or more I/O access methods, and which represents a 
hardware or software system device. 

Opened devices are I/O charmels to devices. 

Multiple opened devices can be open concurrently on the same device. 

A process that opens a device is free to pass the opened device to other processes in the 
same or different jobs. 

BiiN™ Operating System attributes provide a method for defining general purpose opera- 
tions supported by multiple object types. 
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• A process nonnally executes in an environment with four existing I/O assignments: 
standard_input, standard_output, standard_message, and 
user_dialog. 
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You use the byte stream access method or the record access method to perform basic I/O on an 
opened device. This chapter describes the techniques for using the Byte_Stream_AM and 
Record_AM packages to perform basic I/O. 

Packages Used: 

Device_Def s Provides declarations common to different I/O access methods. 

Byte_Stream_AM 

Provides device-independent I/O using streams of bytes. 

Re cor d_AM Provides device-independent I/O for one-record-at-a-time access. 



The examples used in the following sections are parts of two procedures: 
Output_bytes_ex and Output_records_ex. See Appendix X-A for the complete 
listings. 



IV-2.1 Opening and Closing an I/O Device 



When opening a device with an open caU from the Byte_Stream_AM package, the caU 
returns an opened device. When you are through using an opened device, you remove access 
to it with a close call. 

Calls Used: 

Byte_Stream_AM . Open_by_name 

Opens a device given its pathname, creating an opened device object. 

Byte_Stream_AM . Ops . Close 

Qoses an opened device. 



This example uses the Open_by_name call to open a device for reading: 

18 source_opened_device : Device_Defs.opened_device; 

29 source_opened_device := 

30 Byte_Stream_AM.Open_by_name ( 

31 name => name, 

32 input_output => Device_Defs . input, 

33 allow => Device_Def s. readers ) ; 

In the example the open call returns an opened device to the variable 
sour ce_opened_de vice. The input_output parameter specifies the type of I/O for 
the opened device; the type of I/O is set to input for reading. The allow parameter 
specifies how other caUers can use the opened device, while you have it open; the allow mode 
is set to readers indicating that other callers can read from the device. 

When you close an opened device, you remove the connection between your program and the 
device. 

50 Byte_Stream_AM. Ops. Close ( 

51 source opened device) ; 
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IV-2.2 Reading and Writing Bytes 

Once you create an opened device, you can read and write bytes using an I/O access method. 

Calls Used: 

Byte_Str eam_AM . Ops . Read 

Reads bytes from an opened device. 

Byte_Stream_AM . Ops . Write 

Writes bytes to an opened device. 



A simple procedure might: 

1. Declare a fixed-size buffer to hold the bytes read 

2. Declare an opened input device and an opened output device 

3. Open the devices. 

You can declare a simple 4Kbyte fixed-size buffer as follows: 

constant System. ordinal := 4_096; 
array (1 .. BUFSIZE) of 
System . byt e_or dinal ; 
System . ordinal ; 

You can request the niunber of bytes to be read into the buffer using the opened input device 
(in this case, the opened device source_opened_device). A byte count is returned. 

38 loop 

39 bytes_read := Byte_Stream_AM. Ops. Read ( 

40 source_opened_device, 

41 buffer' address, 

42 BUFSIZE); 

43 Byte_Stream_AM.Ops.Write{ 
4 4 dest_opened_device, 
45 buffer' address, 

4 6 bytes_read) ; 

4 7 end loop; 

The Write call writes the data from the buffer to the opened output device (in this case, the 
opened device dest_opened_device). 
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IV-2.3 Handling End-of-File 



The Devic_Def s . end_of_f ile exception is raised when a read call attempts to read past 
the end of an input stream. 

Calls Used: 

Byte_Stream_AM.Ops .Close 

Qoses the caller's opened device. 

Byte_Stream_AM . Ops . At_end_of _f ile 

Checks whether an opened device is at EOF. 
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You can monitor the end-of-file condition using an exception handler. For example, after 
reading records inside a loop in the procedure Output_bytes, a Close call is made when 
end-of-file is detected: 

48 exception 

4 9 when Device_Defs.end_of_f ile => 

50 Byte_St ream_AM. Ops. Close ( 

51 source_opened_device) ; 

An alternative way to check for end-of-file is to use an At_end._of __f ile call. This call 
returns a boolean of true, if the opened device indicates an end-of-file condition. The next 
Read call on this opened device will raise Device_Def s . end_of _f ile. 



IV-2.4 Using Default I/O Connections 



Default I/O connections for standard input and standard output exist in a process's global 
variables, the process global entries. 

Calls Used: 

Process_Mgt . Get_process_globals_entry 
Retrieves the process globals entry. 



You can retrieve a process's standard output with the Get^rocess_globals_entry 
caU. Here is a complete listing of the Hello_OS_ex example which uses this technique: 

1 with Byte_Stream_AM, 

2 Device_Defs, 

3 Process_Mgt, 

4 Process_Mgt_Types, 

5 System; 
6 

7 procedure Hello_OS_ex is 

8 

9 — Function: 

10 — Write "Hello, world!" on a separate line to the 

11 — standard output, using OS packages. 
12 

13 hello: constant string := "Hello, world!" & ASCII. LF; 

14 stdout: constant Device_Defs.opened_device := 

15 Process_Mgt .Get_process_globals_entry { 

1 6 Process_Mgt_Types . standard_output ) ; 

17 begin 

18 Byte_Stream_AM.Ops.Write{ 

19 opened_dev => stdout, 

20 buffer_VA => hello (1) ' address, 

21 length => System. ordinal (hello' length) ) ; 

22 end Hello_OS_ex; 

Normally, your standard output is directed to your terminal. You can redirect standard output 

to another opened device by setting the Process_Mgt_Types . standard_output 

process globals entry. Seethe 

Process_Globals_Support_Ex . Set_standard_output example call in Appendix 

X-A. 

A simple utility that takes input from a device and directs it to standard output is shown below. 
It uses most of the programming techniques previously discussed. 
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Calls Used: 

Byte_Stream_AM . Open_by_name 

Opens a device by creating an opened device for the caller. 

Byte_Stream_AM.Ops .Close 

Qoses an opened device for access. 



9 procedure Output_bytes_ex ( 

10 name: System_Defs. text) 

11 — Input device to read. 
12 

13 — Function: 

14 — Opens the named input device and 

15 — copies bytes from it to the caller's 

16 — standard output, until end-of-file. 

17 is 

18 source_opened_device : Device_Defs.opened_device; 

19 dest_opened_device: Device_Defs.opened_device; 

20 function Opened_device_from_untyped is new 

21 Unchecked_conversion( 

22 source => System. untyped_word, 

23 target => Device_Defs .opened_device) ; 

24 BUFSIZE: constant System. ordinal := 4_096; 

25 buffer: arrayd .. BUFSIZE) of 

26 System. byte_ordinal; 

27 bytes_read: System. ordinal; 

28 begin 

29 source_opened_device := 

30 Byte_Stream_AM.Open_by_name ( 

31 name => name, 

32 input_output => Device_Defs .input, 

33 allow => Device_Def s. readers ) ; 

34 dest_opened_device := Opened_device_from_untyped( 

35 Process_Mgt .Get_process_globals_entry ( 

36 Process_Mgt_Types .standard_output) ) ; 
37 

38 loop 

39 bytes_read := Byte_Stream_AM.Ops.Read ( 

40 source_opened_device, 

41 buffer' address, 

42 BUFSIZE); 

43 Byte_Stream_AM.Ops.Write( 
4 4 dest_opened_device, 
45 buffer' address, 

4 6 bytes_read) ; 

47 end loop; 

48 exception 

4 9 when Device_Defs.end_of_file => 

50 Byt e_Stream_AM. Ops. Close ( 

51 source_opened_device) ; 

52 end Output bytes ex; 



IV-2.5 Positioning Within a Byte Stream 



Prior to reading or writing bytes, the byte pointer for an open device can be set to any byte 
position in a byte stream. 

Calls Used: 

Byte_Stream_AM . Ops . Set_position 

Moves the byte pointer for an opened device to a specified byte offset in 
the byte stream. 
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To set the byte pointer, indicate the opened device and then specify a signed byte offset from 
the starting byte. Positioning can occur: 

• From the beginning of the device 

• From the current pointer position 

• From the end of the file Gast byte plus one). 

If the byte pointer is set beyond the device's end-of-file, a subsequent write to the device 
causes the device to increase to the size indicated by the new byte pointer position. 

IV-2.6 Reading and Inserting Records Sequentiaily 

Reading and writing records sequentially is very similar to reading and writing bytes. Record 
I/O accesses a record as a unit, while byte stream I/O accesses a byte as a unit. 

Calls Used: 

Record_AM . Open 

Opens a device given its pathname. 

Record_AM. Ops. Close 

Qoses an opened device. 

Record_AM . Ops . Read 

Reads a record. 

Record_AM . Ops . Insert 

Inserts a record. 



The following procedure, Output_records_ex, is a general-purpose utility that reads 
records sequentially from a file into a buffer, and then outputs them sequentially using stan- 
dard output. It does the same thing with records that the Output_bytes_ex procedure does 
with bytes: 

• Declares source and destination opened devices 

• Accepts record input fix)m the specified device 

• Outputs the record using standard output. 

The example Output_record_ex sets up a variable length record buffer to read in records 
of any length. The following declaration declares and allocates a variable length buffer: 

58 buffer_size: System. ordinal := 256; 

59 buffer_AD: System. untyped_word := 

60 Ob ject_Mgt .Allocate (buf fer_size/4 ) ; 

61 — 64 words {256 bytes) is the initial buffer 

62 — size. Buffer size is increased as needed. 

63 — The buffer is in a separate object for easy 

64 — resizing. 

65 bytes_read: System. ordinal := 0; 

66 — If record requires multiple "Read" calls, 

67 — then this variable tracks bytes read so far. 

A read_status_VA variable is declared to contain status information about the read call. 
A read_position variable contains the record position for the next read. 
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68 read_status_VA: Record_AM.operation_status_VA := 

69 new Record_AM.operation_status_record; 

70 read_position: Record_AM.position_modif ier := 

71 Record_AM.next; 

The Read call reads records from an input device into a variable length buffer. The buffer is 
resized when it is too small to handle a record. 

91 loop 

92 begin 

93 bytes_read := bytes_read + 

94 Record_AM. Ops. Read ( 

95 source_opened_device, 

96 read_position, 

97 System. address' ( 

98 bytes_read, 

99 buffer_AD), 

100 buffer_size - bytes_read, 

101 status => read_status_VA) ; 
102 

103 — When control reaches this point, "Read" 

104 — succeeded without a length error and 

105 — this loop can be exited. 

106 EXIT; 

If the buffer is too small, a recovery block resizes the buffer by handling the 
Device_Def s . length_error exception. The record buffer is resized by checking the 
length of the buffer for the Read call using read_status_VA . rec_length. 

108 exception 

109 when Device_Defs. length_error => 

110 buffer_size := read_status_VA.rec_length; 

111 if buffer_size = 

112 Record_AM.unknown_length then 

113 buffer_size := 2 * 4 * 

114 Object_Mgt.Get_object_size (buffer_AD) ; 

115 — Double the buffer size if an exact 

116 — new size is not available. 

117 end if; 

118 Object_Mgt.Resize ( 

119 buffer_AD, 

120 (buffer_size+3)/4); 

121 — May make object even bigger than 

122 — requested, but that's OK. 

123 read_position := Record_AM.rest_of_current; 

124 end; 

The buffer is resized, the read_j>osition is set to read the next record, and the Read 
succeeds without a length error. When the record is read, the record can be inserted to the 
standard output. 

127 Recor d_AM. Ops. Insert ( 

128 dest_opened_device, 

129 System. address' (0, buffer_AD) , 

130 bytes_read) ; 

See Chapter IV-9 for more information about record I/O operations. 
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This chapter shows how to create, copy, and delete stream files. To read and write stream 
files, use the access method techniques that Chapter IV-2 describes. 

Packages Used: 

S imp 1 e_F i 1 e_Admi n 

Manages stream files. 

By t e_S t r eam_AM 

Provides device-independent I/O using streams of bytes. 

Record_AM Provides device-independent I/O for one-record-at-a-time access. Con- 

tains the Record_AM .Ops and Record_AM. Keyed_Ops packages. 



A stream file is a file consisting of a contiguous stream of bytes. Figure IV-3-1 shows a 
stream file being opened using byte stream I/O. 
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IV-3.1 Concepts 



For creating, copying, and destroying stream files, you use the Simple_File_Adniin pack- 
age. For basic IJO with stream files, you use the Byte_Stream_AM and Record_AM 
packages. 

lV-3.1.1 What Is a Stream File? 

There are two different classes of files: stream files and structured files. The main difference 
between a stream file and a structured file is that stream files cannot be indexed. But stream 
files can contain records, and you can use record I/O with stream files. For indexed files, you 
must use a structured file organization. 

You create and destroy stream files using the caUs in the Simple_File_Admin package. 
You can use these calls inside transactions, but the file is not created or destroyed until the 
calling transaction commits. 

The system automatically handles disk space allocations for stream files (including file expan- 
sion and volume set selection). You can specify allocations for stream files with calls in the 
Simple_File_Adinin package. This lets you control how much disk space to allocate for 
stream files. Stream files are allocated in this manner: 
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• Permanent stream files with pathnames are created on the same volume set as the directory 
or subdirectory indicated by the pathname. 

• Temporary files without pathnames are created on the default system volume set, unless 
specified otfierwise. 

These type rights affect stream files: 

read rights Required to open a stream file for input. 

write rights Required to open a stream file for output. 

control rights Required to allocate disk space for a file and to otherwise manipulate a 

file. 

lV-3.1.2 Using Access Methods with Stream Files 

You can access stream files using either byte stream or record I/O. In general, you should use 
byte stream I/O to access a stream file, although you can use record I/O to access records in 
stream files. Mixing I/O methods when accessing stream files can cause problems. See the 
Simple_File_Admin package in the BiiN^lOS Reference Manual for guidelines. 

Stream files are not transaction-oriented; transactions and transaction operations don't affect 
I/O operations or other operations on stream files. 

IV-3.1.2.1 Byte Stream I/O 

You perform byte stream I/O on stream files using the calls in the Byte_Stream_AM pack- 
age. These calls let you open a stream file for input or output, read bytes from a stream file, or 
write bytes to a stream file. You can position a byte pointer to any byte in the file prior to 
reading or writing. 

IV-3.1.2.2 Record I/O 

You perform record I/O on stream files using the calls in the Record_AM package. These 
calls let you open a stream file for record input or output, read records from a stream file, or 
write records to a stream file. 

During a Record_AM read operation, each record is read up to the next termination character. 
During a write operation, a termination character is appended to delimit the boundaries be- 
tween records. The termination character (term_char) is set up when the stream file is 
created. It defaults to an ASCII line feed. 

You can use stream files for pages of text. Each line of text is a record. A record containing 
only an ASCII fonn feed (that is, a page mark) is the end of a page of text Page marics can be 
created using a Record_AM . Ops . New_j3age call. 

Figure IV-3-2 shows possible line formats. The angle brackets <> indicate a required element. 
The braces { } indicate a repeating element. 
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empty-line 


:= <preceding-delimiter> <terminator> 


data-line 


: = <preceding-delimiter> { <data character> } 
Kterminator or EOF> 


page-mark 


:= <preceding-delimiter> <form-feed> 
<terminator> 



Figure IV-3-2. Line Formats for Stream Files 



preceding-delimiter 

is either a terminator or the beginning of the file and is not part of the line 
that follows it 

data-character is any character except a temiinator. 

terminator is the file's specified termination character. 

The definition of the page mark excludes its termination by the end-of-file marker. A form 
feed character written without the trailing terminator is treated by record I/O as a data charac- 
ter. To be compatible with stream files that use byte stream I/O, the data line is allowed to be 
terminated by the end-of-file marker. 

Other record-oriented characteristics of stream files include: 

• Each record in a stream file has a unique, system-maintained record ID. 

• A termination character cannot be part of a record. 

• Records cannot be indexed. 

• Records cannot be deleted. 

• Records can be read sequentially or randomly based on the physical ordering of the records 
in the file. 

• Records can only be inserted at the end of the file. 

• Records can be updated as long as the size of the record doesn't change. 

• Stream files don't participate in transactions, don't support record locking, and don't sup- 
port file logging. 



IV-3.1 .3 Temporary Files 



Temporary files are stream files that are not named when created. They exist for the duration 
of the current job unless they are explicitiy saved and named. 

You use a special Simple_File_Admin call, Create_unnamed_f ile, to create a tem- 
porary file. If you intend to create a temporary file and then save it later, it's best to indicate 
its volume set when the file is first created. That way, you can make sure that the pathname 
you assign the file (when you save it) is on the correct volimie set. 

• You can explicitiy destroy a temporary file by making a De st roy_f ile call. 

• You can name a temporary file by making a Save_unnamed_f ile call. 
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• Once a file is named, it has a corresponding directory entry. By deleting this entry with a 
Directory__Mgt . Delete call, you get rid of the passive version of the file object. The 
file goes away when the last AD that references it goes away. 



IV-3.2 Techniques 



This section provides the techniques for creating, copying, and destroying stream files. After 
reading this section you wiU be able to: 

• Create a stream file 

• Copy a stream file 

• Empty a stream file 

• Delete a stream file 

• Create a temporary stream file. 

The examples used in the following sections are parts of one procedure: Stream_f ile_ex. 
See Appendix X-A for the complete listing. 

IV-3.2.1 Creating a Stream File 

When creating a stream file, you only need to specify the file's pathname to the caU that 
creates your file. The filing system: 

• Creates a stream file using the file's pathname 

• Stores an entry in the new file's directory 

• Returns an AD for the file with all type rights. 

Calls Used: 

Siinple_File_Admin . Create_f ile 
Creates a stream file. 



You specify the file's pathname in the name parameter, which must be a 

System_Def s . text type. The directory where you want to create the file must exist and 

the filename must be unique, or you will get an exception. To create a file use: 

20 Text_Mgt. Set (filename, "my_file_l") ; 

21 filel := Simple_File_Admin.Create_f ile (filename) ; 

22 — Creates a stream file in the current 

23 — directory. 

The rest of the parameters are defaulted. You can specify the number of bytes to preallocate 
for disk storage with the bytes_to_preallocate parameter. The default is no byte 
preaUocation. You can specify an alternate termination character with the term_char 
parameter. The default termination character is an ASCII line feed. 
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iV-3.2.2 Copying a Stream File 

Once you create a file, you can copy its contents to another file. 

Calls Used: 

Simple_File_Adinin . Copy_f ile 

Copies the contents of one file to another. 



You copy a file by specifying the source_f ile and target_f ile parameters. For ex- 
ample: 

28 Text_Mgt. Set (filename, "my_file_2") ; 

29 file2 := Simple_File_Admin. Create_f ile (filename) ; 

30 Simple_File_Admin.Copy_file (source_file => filel, 

31 target_file => file2) ; 

32 — Creates a second file in the current directory, 

33 — and then copies the contents of the first file 

34 ~ to the second. 

You have the option of deallocating unused pages in the second file by setting a shrink 
boolean to true. 

IV-3.2.3 Emptying a Stream Fiie 

You can empty a stream file with one call. 

Calls Used: 

Simple_File_Admin . Empty_f ile 

Empties a file of its contents without deallocating it. 



For example, to empty the contents of a file use: 

36 Simple_File_Admin.Empty_f ile (filel) ; 

37 — Empties the first file. 

If there is more than one caller using the file, the file is not emptied until all caUers have closed 
the file. This default setting can be changed by setting a notif y_if_busy boolean to tme. 
If this parameter is true, Device_Def s . device_in_use is raised when a file is in use, 
and the file is not emptied. 

Empty_f ile is slighdy more complex when done inside a transaction. See the 
Simple_File_Adinin package in the BiiN^IOS Reference Manual. 

iV-3.2.4 Deleting a Stream Fiie 

You can delete a file by simply deleting its directory entry or by destroying the file. 
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Calls Used: 

Directory_Mgt . Delete 

Deletes a directory entry. This may also destroy the referenced object's 
passive version. 

Simple_File_Admin . Destroy_f ile 

Deallocates all parts of the file, but not its directory entry. 

Process_Mgt . Get_process_globals_entry 

Gets the default directory for the stream file. 



To delete a file's directory entry you call Delete, giving the file's pathname in the name 
parameter. For example, to delete a file in the current directory use: 

39 Text_Mgt. Set (filename, "my_file_2") ; 

4 Directory_Mgt .Delete (filename) ; 

41 — The second file's pathname is deleted. The 

42 — second file is destroyed when the last 

43 — reference to it goes away. 

You can also delete a file with the Destroy_f ile call. You need to specify the file's AD 
with the file parameter. This example destroys a temporary file: 

67 Simple_File_Admin.Destroy_file (file3) ; 

68 — Destroys the temporary file before its job 

69 — terminates. If it is not destroyed or saved, 

70 — it goes away when the job terminates. 

This caU only destroys the file, not the file's directory entry. 

If there is more than one caller using the open file, the file is not destroyed imtil aU callers have 
closed the file. The not if y_if_busy parameter can change this. If true, this parameter 
causes the Device_Def s . device_in_use exception to be raised when the file is in use; 
the file is not destroyed when this exception is raised. 

Do not use a Delete call to delete a temporary stream file; use the Destroy_f ile call. If 
you use the Destroy_f ile call in a transaction, the file is not destroyed if the transaction 
aborts. 

IV-3,2.5 Creating Temporary Files 

You can create temporary stream files for intermediate data storage (for example, a work file). 
Temporary files exist for the duration of the current job, and are automatically destroyed when 
the job terminates. 

Calls Used: 

Siinple_File_Admin . Create_unnamed_f ile 
Creates a temporary stream file. 

Passive_Store_Mgt . Home_voluine_set 

Returns an object's home volume set. 

Process_Mgt . Get_process_globals_entry 
Gets a process globals entry. 
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To create a temporary file, you must specify its volume set in the volume_set parameter. 
For example: 

4 5 file2 := Simple_f ile_Admin.Create._unnamed_f ile { 
4 6 Passive_Store_Mgt . Home_volume_set ( 

47 Process_Mgt .Get_process_globals_entry { 

48 Process_Mgt_Types .current_dir) ) ) ; 
4 9 — Creates a temporary file in the current 

50 — directory using the current directory's 

51 — volume set. 

This example retrieves the home volume set for the current directory and uses it as the volume 
set for the file. You can name a temporary file and save it as a permanent file using 

Simple_File_Aclinin . Save_unnamed_f ile. 

IV-3-3 Summary 

• Use stream files to read and write bytes. 

• You cannot index stream files. 

• Stream files don't participate in transactions. 

• Temporary files exist only for the duration of the current job unless you explicitly name 
and save them. 
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This chapter discusses the use of windows on character tenninals, including tenninal manager 
support for windows and I/O access methods. 

Packages Used: 

Character_Terminal_Mgt 

Manages character tenninals. 

Terminal__Def s 

Defines constants, types, and exceptions used by the terminal service 
packages. 

Window__Ser vices 

Provides windows on character and graphics terminals, including pull- 
down menus. 



A window is a portion of the terminal screen through which a user interaas with an application 
program. In general, the screen can contain multiple windows; the windows do not overlap. 
The user controls the size, location, and visibility of windows, but the application program 
controls the contents. The application uses one of three access methods to do VO to a window. 
Coordinate systems describe tiie location of windows with respect to the screen and the loca- 
tion of specific points within a window. A user can move a window, resize it, pan it vertically 
or horizontally, and request that it be closed. Windows can have pop-up menus. Terminal 
managers provide support for windows and I/O access methods. 

IV-4.1 Concepts 

The following terms are used throughout this chapter: 

physical terminal The physical terminal is a video display device with a keyboard. 

user The human being interacting with the system through a tenninal. 

application The application program being run by the user. Typical examples are text 

editors and spread-sheet programs. The term "application" also covers any 
additional software that lies between the application and the operating sys- 
tem. 

virtual terminal A device that, to an application, is indistinguishable from a physical ter- 
minal. A virtual terminal provides a screen-like drawing space for the out- 
put of characters or graphics, and a keyboard and mouse for input. 

frame buffer The drawing space of a virtual tenninal. An application writes to the 

frame buffer associated with a virtual terminal. The frame buffer is visible 
to a user through a rectangular screen area; that is, through a window. The 
part of the frame buffer that is visible through a window is called the view. 

window The rectangular screen area where the view appears. Many windows may 

be visible on the screen at the same time. 

view The visible part of the frame buffer. The view may not be larger than the 

frame buffer. 

input focus There may be many windows on a terminal, but there is only one keyboard 

(and mouse). The input focus is that virtual terminal to which keyboard 
and mouse input are connected at a given time. 
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Figure IV-4-1 shows the relationships among views, windows, frame buffers, and a physical 
terminal. 
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Figure rV-4-1. Windows Displayed on a Physical Terminal 



IV-4.1.1 Terminals and Windows 

The current system release supports character temiinals. Graphics tenninals will be supported 
in a future release. 

Qiaracter terminals have some subset of the features specified in the ANSI X3.64 standard: 
character insertion and deletion, line insertion and deletion, cursor positioning, scrolling, and 
so forth. The DEC VT-100^ is a typical character terminal. 

The screen of a character terminal is divided into a Cartesian grid of fixed- width, fixed-height 
character cells each of which contains a displayable character. Each ceU is identified by {x,y) 
coordinates, starting with (1,1) in the upper-left hand comer. The x coordinate increases to the 
right, and the y coordinate increases downwards. Graphics terminals have all the capabilities 
of character terminals and others as weU; for example, line drawing, line and point attributes, 
and raster primitives. The graphics tenninals to be supported are (TBD). 

The screen of a graphics terminal is divided into a Cartesian grid of pixels, each of which is 
identified by {x,y) coordinates in the same fashion as character cells on a character terminal. 

On a character terminal, a window consists of a rectangular grid of character cells; on a 
graphics terminal, it consists of a rectangular grid of pixels. The size of the window is initially 
suggested by the application, and may be modified by the user. Note the following: 



^DEC VT-100 is a trademark of Digital Equipment Corp. 
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• The system constrains windows on character temiinals to be as wide as the screen. 

• Character tenninal windows do not overlap. Graphics terminal windows can overlap. 

IV-4.1.2 Accessing Windows 

An application does I/O to a physical terminal through the frame buffer and keyboard as- 
sociated with the application's virtual tenninal, but we wiU talk about I/O to windows since 
they provide the visible evidence of I/O activity within a frame buffer. 

An application creates and manipulates windows through the Window_Services package, 
which provides a procedural interface for creating and destroying windows, manipulating the 
characteristics of windows, and building and installing menus on windows. 

Once a character terminal window has been set up, three access methods are available for 
performing I/O in the window: 

• Character_Display_AM 

• Byte_Stream_AM 

• Record_AM . 

Character_Display_AM provides operations for doing character I/O to windows, treating 
the window as a two-dimensional grid of character cells. Operations are provided for input, 
output, insertion and deletion of lines and characters, cursor movement, etc. 

Char act er_Display_AM is the primary access method for character terminal windows, 
but an application can also use Byte_Stream_AM and Record_AM. Under these access 
methods, I/O to a window is treated as a stream of characters. Operations are provided for 
input, output, etc. Several of these operations have slightly different semantics when they are 
used to access windows. 

An application mixes access methods when it calls the Open function of one access method 
and then uses the returned opened device to call operations provided by other access methods. 
An example would be calling Byte_Streain . Ops . Open and then using the returned 
opened device object to call Char act er_Display_AM . Ops . Insert_line. The extent 
to which access methods can be mixed is device-dependent. 

IV-4.1.3 Window Coordinates 

Window_Ser vices treats terminals and virtual terminals as two-dimensional display sur- 
faces, and provides operations that refer to positions on the surfaces. A position is specified by 
a pair of coordinate values within a coordinate system. 

An application using Window_Services may need to access either character positions or 
pixel positions. Accordingly, Window_Services provides both a character-oriented coor- 
dinate system and a pixel-oriented coordinate system. Each operation that takes parameters to 
describe a position also includes a boolean parameter to select which coordinate system is used 
to interpret the values. 

Figure IV-4-2 shows the position of a window relative to the screen as measured in the 
character-oriented and pixel-oriented coordinate systems. In each case, the horizontal com- 
ponent of the position is given first followed by the vertical component. The upper left comer 
of the window is in the 4th character column of the screen (counting from the left) and the 5th 
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character row (counting from the top). Thus the character-oriented coordinate system position 
is (4,5). The same comer is in pixel column number 10 (1 is at the left), and pixel row number 
40 (1 is at the top). Thus the pixel-oriented coordinate system position is (10,40). 




SSG\windserv 

Figure IV-4-2. Window Services Coordinate Systems 



IV-4.1.4 Terminal Attributes 



There are a number of attributes that affect the I/O done to a window. Terminal attributes are 
defined on a per-terminal basis and affect all the windows on the terminal. Table IV-4-1 lists 
these attributes. The table provides suggested defaults; the actual defaults are device depend- 
ent. 

See the Terminal_Def s package for more detailed information. 

Table IV-4-1. Terminal Attributes 



Attribute 


Default Setting 


erase 


BS (<Ctrl-H>) 


cancel 


NAK (<Ctrl-U>) 


newline 


LF (<CtrI-J>) 


EOL 


NUL(<CtrI-@>) 


EOF 


EOT(<CtrI-D>) 


literal_next 


SYN(<Ctri.V>) 


redraw_input_line 


DC2 (<Ctrl-R>) 


suspend 


SUB (<CtrI-Z>) 


intemipt 


ETX (<Ctri-C>) 


termination 


DEL (<Ctrl-?>) 


debug 


STX (<Ctrl-B>) 
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Table IV-4-1: Terminal Attributes (cont) 


Attribute 


Default Setting 


stop 


DC3 (<Ctrl-S>) 


start 


DCl (<Ctrl-Q>) 


do_flow_control_oat 


wait_for_any 


do_flow_control_in 


false 


ignoiejbieak 


false 


do_paiity checking 


tiue 


bad.char handling 


discaidjbad.char 


visual_bell 


false 


baud_rate 


b_9600 


|Aysical_char_detail 


(none, one, eight) 



IV-4.1 .5 The Input Model 



An application running in a window obtains user input by calling the Read procedure in one 
of the four access methods mentioned earlier. The Read procedure returns one or more input 
events of a certain type. This section characterizes the various types of input and presents the 
general input model. 

If a keyboard were the only input device of a terminal, and a terminal did not provide multiple 
windows, the input model would be simple. To obtain keyboard input, an application would 
call the appropriate Read procedure, which would (optionally) block until the user typed 
something. If the user typed while no application was reading, the data would be stored in an 
input event queue until the application requested it. 

This simple input model is inadequate because there are other types of input: 

Mouse input A terminal may have a mouse in addition to a keyboard. The mouse intro- 

duces a new type of input event. (Input events should not be confused with 
the events defined by Event_Mgt. As used here, the term event 
describes an action performed by the user.) A mouse input event contains 
information about the position of the mouse in addition to the state of its 
buttons. Furthermore, an application that wishes to read input from both 
the mouse and keyboard must be able to distinguish between keyboard 
input events and mouse input events. 

Window-related input 

Imagine a clock application that does nothing but draw a clock face in the 
fi^ame buffer, updating it each second. According to the material presented 
so far, the user sees a window that may be much smaller than the fi"ame 
buffer itself, in which case only a small part of the clock face is visible, 
and the application is not particularly useful. The application could im- 
prove its user interface if it could draw a smaller clock face that would fit 
within the view of the frame buffer. To do this, the application would need 
a way to find out about changes in the origin and size of the view. 

Window_Services makes that possible by defining a nimiber of 
window-related input events that can inform the application about events 
that occur to the window; the appUcation can then take whatever action is 
appropriate. 

User-defined input The user may define input events. 
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The system provides an enumeration type, Terminal_Def s . input_enum, that denotes all 
four types of input events (the literals from menu_it em_picked through 
scroll_requested denote window-related input): 

keyboard The user typed something on the keyboard. 

mouse The user moved the mouse, or its buttons, or both. 

menu_item_picked 

The user picked an item from a menu. 

f ocus_changed The user changed the input focus. 

overlap_changed 

The user changed the window's overlap state. 

si ze_changed The user changed the window's size. 

view_changed The user panned the view to a new position on the frame buffer. 

position_changed 

The user moved the window to a new location on the screen. 

close_requested 

The user requested that the window be closed. 

scroll_requested 

The user requested that the window be scrolled. 

user_def ined An application initiated a user-defined input event 

The system provides another type, Terminal_Def s . input_type_mask, that denotes a 
set of these input types. There is always an input type mask in effect for a given virtual 
terminal. Newly arriving input events are accepted if their type matches one of those in the 
input type mask for that window; otherwise they are discarded. When a new input event is 
accepted, it is stored in an input event queue or passed immediately to an application blocked 
on a read call. 

I V-4.1 .6 The Output Model 

Output to a window is accomplished through output to the window's frame buffer using one of 

TM 

the three access methods. See the BUN I OS Reference Manual. 

I V-4.1. 7 Overlapped Windows 

As mentioned earlier, the system supports multiple windows on a single physical terminal. 
The rest of this chapter describes window_Ser vices, the interface for creating, destroying, 
and controlling windows. But before describing this interface, a more detailed discussion of 
windows is required. 

RecaU that an application draws figures or characters on a drawing space called a frame buffer. 
A rectangular portion of the frame buffer, the view, is mapped to a rectangular area on the 
screen. This rectangular area is called the window and is the same size as the view. The origin 
of the view is measured relative to the frame buffer, and the position of the window is 
measured relative to the screen. 

Figure IV-4-3 shows these relationships. 
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Figure IV-4-3. Relationship Between Window and View 



Figure IV-4-3 shows a single window, but in general it is possible to display multiple windows 
on a single terminal screen and to have the windows overlap like sheets of paper on a desktop. 
(Support for overlap is device dependent, with each device manager defining the level of 
support it provides; in particular, overlap is not supported on character terminals.) 

Overlapped windows are ordered in dLfront-to-back relationship that determines what is dis- 
played in areas of the screen that are covered by more than one window. Some windows may 
be partially or wholly obscured by windows that are logically in fi-ont of them. 

Figure IV-4-4 shows a possible layout for three windows whose front-to-back ordering is (Wl, 
W2, W3). W2 is partially obscured by Wl, but W3 is imobscured since it does not overlap 
withWlorWl 
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Figure IV-4-4. Example of Overlapped Windows 
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IV-4.1.8 Some Key Points 



• Windows are independent of one another. The abstraction presented to an application is 
that it can draw images on a frame buffer that is completely independent finom aU other 
frame buffers. The application can treat the frame buffer as if it were an entire screen. 
Since frame buffers are independent, so are windows. 

• An application cannot affect the screen outside its window. All drawing operations are 
clipped to the boundaries of the frame buffer. Only the portion of the frame buffer inside 
the view is visible in the window. Screen areas outside the window belong to other ap- 
plications or are unused. 

• A frame buffer's size is fixed when it is created, and never changes. The corresponding 
view cannot be enlarged beyond the edges of the frame buffer. Thus a window can never 
be larger than its frame buffer. 

• The user controls the layout, size, and front-to-back ordering of windows, but an applica- 
tion has full control of a window's contents. This includes drawing on the frame buffer and 
panning the view over the frame buffer. Everything else is controlled by the system. This 
includes clipping, maintaining the coordinate system for the frame buffer, and changing the 
layout, size, and visibility of windows. The system software that interacts with the user to 
perform these tasks is called: 

- The character terminal user agent for character terminals. 

- The graphics terminal user agent for graphics terminals. 
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IV-4.1.9 Resizing a Window 



If the user changes the size of the window, then the view's size must also change so that a 
different portion of the frame buffer becomes visible in the window. But what is the position 
of the new view in the frame buffer? As shown in Figure IV-4-5 there are several possibilities. 

The figure shows a frame buffer and view before and after the view size is doubled. In (b), the 
left top comer of the new view is at the same position as the left top comer of the old view. In 
(c), the middle of the new view is at the same position as the middle of the old view. In either 
case, the application had no opportunity to control the position of the view and hence the 
window's contents, which means that the user's ability to control layout is in conflict with the 
application's responsibility to control contents. 
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Figure IV-4-5. Example Showing Two Possible Resize Rules 

To address this problem, Window__Services allows an application to specify a resize rule 
that describes the desired effect of a resize operation on the view origin. Whenever possible, 
this rule is used to resize a window. Thus the application indicates its wishes before the resize 
operation occurs. 

A resize rule identifies a stable point within the frame buffer by describing its position relative 
to the view. The stable point occupies the same position relative to the view's borders after the 
resize as before the resize. For example, if the resize rule is LT the left top comer is the stable 
point. The frame buffer contents that appeared in the left top comer of the window before the 
resize stiU appear in the left top comer after the resize. Figure IV-4-6 illustrates this by 
showing a frame buffer and view before and after a resize that enlarges the view. The resize 
rule is LT. After the resize operation, the same contents still appear in the left top comer of the 
window. 
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Figure IV-4-6. Left Top Resize Rule 



Resize rules are two-character strings. The first character describes the stable point's horizon- 
tal position, and the second character describes its vertical position. Legal resize rules allow L, 
M, and R for the first character, indicating left, middle, and right, and T, M, and B for the 
second character, indicating top, middle, and bottom. 

Two other characters are allowed in either position of a resize rule: 

F The horizontal or vertical dimension is fixed. Any point in the contents is 

stable relative to the left and right borders or top and bottom borders. The 
window cannot be resized in the corresponding dimension. 

C The position of the window's contents remains as specified, and its borders 

move as required to perfomi the resize. 

An attempt to move the window partially off the screen moves the contents 
as required and adjusts borders as necessary. For example. Figure IV-4-7 
shows a screen and a window with the CC resize rule. An attempt to move 
the window partially off the screen to the right would move the window's 
contents the requested distance and clip the window and view on the right 
to fit 
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Figure rV-4-7. Contents Resize Rule Example 



IV-4.1.10 Basic Window Operations 

The above describes the basic functions of Window_Services; the following is a list of the 
corresponding calls: 

Get_Window_Services_Attr_ID 

Returns the windowing attribute ID. 

Create_window Creates a window on a tenninal. 

Destroy_window 

Destroys a window on a terminal. 

Get_terminal Returns the tenninal containing a window. 

Change_view Moves a window's view over its frame buffer to a (new) origin. 

Set_resize_rule 

Sets a window's resize rule. 

Get_resize_rule 

Returns a window's resize rule. 

Get_window_status 

Returns a window's status. 

Insert_input_event 

Inserts an input event into a window's input event queue. 

See the Window_Services package for more information. 

iV-4.1.11 Window Style 

An application can control two aspects of a window's style: 

Interactions The application can choose what user-interactions are permitted for a win- 

dow. These interactions include generating a close request, moving the 
window, re-sizing the window, and panning the window vertically or 
horizontally. 

Appearance The application can choose whether a window has title and information 

bars, and what the contents of the bars is. The application can also affect 
the size and position of sliders within scroll bars. 



IV=4=12 



PREUMINARY 



Note that the appearance of a window may be related to the set of permitted interactions. For 
example, graphics temiinals may add scroll bars to a window and use the scroll bars to specify 
panning operations. The appearance and attributes of border areas like scroll bars are device 
specific. 

Window_Services provides two calls for controlling the elements of a window's style: 

• Get_window_style 

• Set_window_style 

These calls enable the application to control border areas and window interactions. The opera- 
tions are fully described in Window_Services, but several points are worth emphasizing: 

• Some combinations of border areas are not permitted. The exact combinations permitted 
are defined by each device manager. All devices allow a window with no border areas. 

• Illegal combinations of border areas are silently transformed into legal combinations. If an 
application needs to know what border areas are actually present, it can call the 
Get_window_style operation. 

• The contents of a border are maintained even if the border area is not present. For example, 
the application can supply text for the information line even if the line is not currently 
present. Then, when the information line is added, the text appears. 

IV-4.1.12 Menus and Windows 

Pull-down menus can be associated with windows. The number of menus per window and the 
menus' features are device dependent, but as a minimal level of support, all devices support a 
menu consisting of a single list of text items that can be selected from the keyboard. TTiis 
section describes the full level of support. 

IV-4.1.12.1 Menu Hierarchy 

A pull-down menu is a three part hierarchy: 

Menu group A menu group is a collection of menus (see below). A window can have 

zero or more menu groups, up to a device-dependent limit. 

Menu A menu is a collection of menu items (see below). A menu group can have 

zero or more menus, up to a device dependent limit. Each menu has a title. 

Menu item A menu item is text or a bitmap (on devices that support bitmaps). A 

menu can have zero or more menu items, up to a device dependent limit. 

Figure IV-4-8 shows the preferred layout for a typical menu group. The menus in the group 
appear side by side in a. Menu bar, which displays the title of each menu. The character 
terminal user agent defines how menu items are selected. 
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Figure IV-4-8. Menu Bar and Pull-down Menu 



Full menu support includes the following additional features. (Some device managers do not 
support all these features.) 

• A menu item can have a check mark in front of it. The meaning of a check mark is 
application dependent. A typical use is to indicate the most recent item selected from the 
menu. 

• A menu item can have a character associated with it. The character is displayed along with 
the menu item. The character can be typed to select the item from the menu. Items that do 
not have a character can only be selected by using the mouse. 

• A menu item can be disabled. A disabled menu item cannot be selected. Disabled menu 
items are displayed in gray. 

iy-4.1.12.2 Building and Installing a Menu 

An application builds a menu by building the menu's DDef description. This is done by using 
the Data_Def inition_Mgt package, as desribed in the Window_Services .Ops pack- 
age. The end result is that the application obtains an AD for tiie menu group. 

The application then installs the menu group in a window, supplying the menu group AD and 
an ID for the menu group. This ID is analogous to the menu and menu item IDs. It is used in 
subsequent references to the menu group and is included in the input event passed to the 
application when a menu item is selected. After installing the menu group, the application no 
longer needs the AD and can discard it 

After installing the menu group, the application can enable and disable menu items, place and 
remove a check maik in front of items, and even replace the text of a text item. 
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To disable the user's ability to invoke menus in a menu group, the application removes the 
menu group from the window. 

Window_Services provides the following operations for installing menus: 

Install_menu_group 

Installs a menu group in a window and gives the group an ID. 

Remove_menu_group 

Removes an installed menu group from a window. 

Menu_group_enable 

Enables or disables a menu group. 

Me nu_i t em_ch e c k 

Adds or removes a menu item checkmark. 

Menu_item_enable 

Enables or disables a menu item in an installed menu group. 

Replace_menu_item_text 

Replaces the text of a menu item. 



IV-4.1.13 User Agents 

As noted earlier, the user controls the layout of windows; that is, the user controls the size, 
position, and overlap of windows, as well as which window is the input focus. The system 
provides this control through a user agent, which is software that interprets some user actions 
as requests to manipulate windows. 

For each tenninal in the system, there is a user agent that: 

• Parses tenninal input 

• Interprets special input sequences as user commands to manipulate the display. 

• Calls the needed operations. 

There is cuirently one user agent defined, for character terminals. See the "Character Terminal 
User Agent" appendix in the BUN™ /OS Reference Manual. 

IV-4.1.14 Character Terminal Manager 

See the Character_Terminal_Mgt package for more information about the character 
tenninal manager. 

IV-4.1.15 Character Terminal Manager Support for Input Operations 

The general windows input model is described on page IV-4-6. The character terminal 
manager supports that model with the following clarifications. 

The character tenninal manager generates all defined input event types except mouse, 
overlap_changed, and user_def ined. 

An application uses Char acter_Display_AM . Ops . Read to read the input events of a 
window opened using Character_Display_AM. Ops . Open. 

An application can use the Set_input_type_mask call of one of the access methods to 
specify the input events that are accepted, and later read, from a window. 
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The Read call of Recor d_AM and Byte_Stream_AM can be mixed with the Read call of 
Character_Display_AM as follows. The Read call of Record_AM and 
By te_Stream_AM only returns one input event type, keyboard input If an application calls 
Read in Byte_Streani_AM or Record_AM Read for a window whose current input mask 
does not include keyboard input, the keyboard input type is added to the current input mask. 
(The keyboard type is not subsequently removed from the input mask unless the application 
expHcitly requests that action using Set_input_type_mask.) The Read call searches the 
input buffer of the virtual terminal for keyboard input. All input events with types other than 
keyboard are discarded until keyboard input is found. The keyboard input is dien returned to 
the user. If no keyboard input is found and the block parameter is true, the application 
blocks until keyboard input arrives. 

With respect to reading keyboard input, the Read functions of Char act er_Display_AM 
and Byte_Stream_AM have the same semantics. If the window is in line editing mode and 
keyboard input is currently at the front of the input queue, then characters are copied to the 
caller's buffer until the number of characters requested is reached, an end of line delimiter is 
encoimtered, or some other type of input event is encoimtered. If the window is not in line 
editing mode and keyboard input is currently at the front of the input queue, then characters are 
copied to the caller's buffer irntU the number of characters requested is reached, some other 
type of input event is encountered, or there is no more input currently available for the win- 
dow. 

The Read function of Record_AM is exactly the same with one exception. If the window is 
in line editmg mode and the size of the line is greater than the length of the read request, then 
the number of bytes requested is copied to the caller's buffer and the caller receives a 
length_error exception. The remainder of the line can be read by calling Read with the 
rec_position parameter set to rest_of_current. 

IV-4.1.16 Character Terminal Manager Support for Output Operations 

The general windows output model is described on pages IV-4-7. The character terminal 
manager fully supports that model. 

For more information about specific input and output operations, see the Byte_Stream_AM, 
Record_AM, and Char act er_Display_AM packages. 

IV'-4.t.17 Character Terminal Manager Support for Access Method Operations 

The character terminal manager supports Byte_Stream_AM, Record_AM, and 
Char act er_Display_AM. 

IV-4.1.17.1 Character Terminal Manager Support for Byte_Stream_AM 

The character terminal manager supports all the operations of Byte_Stream_AM except for 
the following: 

• Set_position 

• Truncate . 

Several Byte_Streain_AM operations have different semantics with windows: 

• Open and Get_device_inf o take a window device as a parameter, instead of a ter- 
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• Get_device_ob ject takes an opened device and returns the window device that was 
opened to get the opened device, rather than the tenninal on which the window resides. 

• Enable_input_notif ication will signal an action when any input is in the input 
queue, but the application may not receive any input (for example, because of the settings 
of the input mask or because of device limitations). If this happens and the application 
does not wish to block when it perforais a subsequent Read operation, it should set the 
block parameter of Read to false and be prepared to receive no input. 

IV-4.1.17.2 Character Terminal Manager Support for Record_AM 

The character terminal manager supports all the operations of Record_AM except for the 
following: 

Delete 

Insert 

Insert_control_record 

Lock_all 

Set_position 

Truncate 

Unlock 

Unlock_all 

Update 

Write_control_record . 

There are several restrictions in accessing windows by Record_AM. The only access mode 
supported is physical sequential. The sequential positions supported for Read are next and 
rest_of_current. The only write position supported is af ter_last. The operations 
not supported are Set_position, Write_control_record, Rewrite, Delete, 
Truncate, Lock_all, and Release. 

Several Record_AM operations have different semantics with windows: 

• Get_device_inf o and Get_device_ob j ect have the same semantics as their 
counterparts in Byte_Stream_AM. 

• Open operates on a window device instead of a terminal, and the extend, 
single_rec_lock, read_ctl_rec, and load parameters arc ignored. 

• Write writes a line to the window. The line terminates at the end of the write and the 
cursor moves down one row or moves to the beginning of the next row depending on the 
current output attributes. 

• New_line and New_page are interpreted appropriately for windows. New_line 
causes a line feed character to be written to the frame buffer. (Depending on the output 
attributes in effect for the window, other characters such as a carriage return may also be 
written to the frame buffer.) New_j5age clears the frame buffer to the background color 
and leaves the cursor at the first colimm of the first row. 

• Get_st atus returns an AD to a record of information about the current status of a win- 
dow. Most fields are set to constant values and are not meaningful for windows. The only 
meaningful fields are input_output, usage, operation_completed, 
last_call, rec_length, and at_EOF. If the length of the current record cannot be 
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deteraiined (because the user has not typed a line tenninator), rec_length is set to the 
unknown_length constant defined in Record_AM. The at_EOF field is set to true 
when an end-of-file character is encountered and all previous user input has been read. 
These fields are updated after each Record_AM operation. 

• The above comments about Enable_input_notif ication and Read (see 
"Character Terminal Manager Support for Byte_Str eam_AM") are also applicable here. 

IV-4.1.17J Character Terminal Manager Support for Character_Display_AM 

The character terminal manager implements all the operations of Character_Display_AM 
except Font_list. 

Several Character_Display_AM operations have different semantics with character ter- 
minals. 

• Set_terminal_attr and Set_window_attr have the normal semantics except that 
a few attributes are not relevant to character terminals and are ignored. Those attributes are 

mouse_saiiipling, f ont_index, background_color, and text__color. 

• The above comments about Enable_input_notif ication and Read (see 
"Character Terminal Manager Support for Byte_Stream_AM") are also applicable here. 

IV-4.2 Techniques 

This section shows you some techniques for using Window_Services: 

• Obtaining an AD for the underlying temiinal 

• Creating a window 

• Setting a window's attributes 

• Setting a window's style. 

These techniques are shown through excerpts fi-om the Simple_Editor_ex procedure. 
Simple_Editor_ex is a simplified screen editor allowing certain operations on an ASQI 
text file. 

Appendix X-A contains the complete listing of Simple_Editor. 

IV-4.2.1 Obtaining an AD for tiie Underlying Terminal 

Calls Used: 

Window_Services . Ops . Get_terminal 

Retums the terminal containing a window. 



One of the editor's first tasks is to create a new window from the old opened window. This 
requires the editor to obtain an AD for the underlying terminal, as in the following call to 

Get terminal: 
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837 — Create new window from old opened window. 

838 old_window := Character_Display_AM.Ops. 

839 Get_device_ob ject (Process_Mgt .Getjprocess_globals_entry { 

840 Process_Mgt_Types.standard_input) ) ; 

841 under lying_terminal := Window_Services.Ops. 

842 Get terminal (old window); 



IV-4.2.2 Creating a Window 



Calls Used: 

Window_Services . Ops . Create_window 

Creates a window on a terminal. 



After obtaining the underlying terminal, the editor needs to create a new window in which the 
editing operations can take place. To do this, the editor calls Great e_window: 

843 edit_window := Window_Services.Ops.Create_window( 

84 4 terminal => underlying_terminal, 

84 5 pixel_units => false, 

84 6 fb_size => Terminal_Defs.point_info' { 

847 last_column, frame_rows), 

848 desired_window_size => Terminal_Def s.point_info' ( 

849 last_column, preferred_window_rows) , 

850 window_pos => origin, 

851 view_pos => origin); 

IV-4.2.3 Setting a Window's Attributes 

Calls Used: 

Window_Services .Ops . Set_window_attr 
Modifies a window's attributes. 



Next, the editor is changes some of the window's default attributes by modifying selected 
fields of window_at tributes and then calling Set_window_attributes. 

832 window_attributes : Terminal_Defs.window_attr := 

833 Terminal_Def s .def ault_window_attr ; 

852 — Set window's input and output attributes 

853 — change from default: 

854 window_attributes.enable_signal := false; — for ''C '^B 

855 window_attributes .line_editing := false; — for '^H 

856 window_attributes .echo := false; 

857 — NOTE: track_cursor NYI (use user agent to change view) 

858 window_attributes.track_cursor := true; 

859 Window_Services.Ops.Set_window_attr { 

860 window => edit_window, 

861 attr => window_attributes, 

862 attr_mask => (others => true) ) ; 

iV-4.2.4 Setting a Window's Styie 

Calls Used: 

Window_Services . Ops . Set_window_style 

Modifies a window's style information. 
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The editor's final task prior to opening the window for editing is to define the window's title 
6ar by calling Set_window_style: 

863 — Set Title and Info lines 

864 Text_Mgt. Set (new_wlndow_lnfo. title, flle_name) ; 

865 Wlndow_Servlces.Ops.Set_wlndow_style ( 

866 window => edlt_wlndow, 

867 new_lnfo => new_wlndow_info, 

868 style_llst => (others => true) ) ; 



IV-4.3 Summary 



• A window is a portion of the terminal screen through which a user interacts with an ap- 
plication program. In general, the screen can contain multiple windows, and the windows 
can overlap. Both character and graphics terminals can have windows. 

• An application creates and manipulates windows tlirough the window__Service s pack- 
age, which provides a procedural interface for creating and destroying windows, manipulat- 
ing the characteristics of windows, and installing menus on windows. 

• Once a character terminal window has been set up, four access methods are available for 
performing I/O in the window: Character_Display_AM, Byte_Stream_AM, and 
Record_AM. 

• Window_Services offers both character-oriented and pixel-oriented coordinate systems. 

• The user controls the layout, size, and visibility of windows, but an application has fiill 
control of a window's contents. 

• Resize rules allow an application to specify a stable point in the view when a window is 
resized. 

• An application can control two aspects of a window's style: the user interactions permitted 
for the window and the window's appearance. The window's appearance and the user's 
interactions may be related (for example, through border areas). 

• Pull-down menus can be associated with windows. The nimiber of menus per window and 
the menus' features are device dependent, but as a mimimal level of support, all devices 
support a menu consisting of a single list of text items that can be selected from the 
keyboard. 

• PuU-down menus have a three-part hierarchy: menu group, menu, and menu item. There 
are two phases to menu manipidations: building the menu and using the menu. 

• Window_Services provides a way for applications to find out about changing view and 
window information in a timely maimer by defining a number of Window_Services 
input events that can be read by an application reading fi-om a window. These input events 
inform the application about events diat occur to the window. The application can then 
take whatever action is appropriate. 
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This chapter shows how to do I/O to a character display device. 

Packages Used: 

Char act er_Display_AM 

Provides device-independent I/O to character display devices such as 
printers, plotters, and windows on character and graphics tenninals. 

Window_Ser vices 

Provides windows on character and graphics terminals, including pull- 
down menus. 

Terminal__Def s 

Defines constants, types, and exceptions used by the terminal service 
packages. 



IV-5.1 Concepts 



This section presents an overview of character display devices and how an application accesses 
them using the Character_Display_AM . Ops package. 

IV-5.1 .1 Character Display Devices 

A character display device displays and manipulates ASCII characters on a two-dimensional 
surface. The most common example of a character display device is a window on the screen of 
a character or graphics terminal. Windows are virtual devices through which I/O is done to a 
physical terminal. Another example of a character display device is a printer. 

The operations for character display devices include input, output, cursor movement, 
manipulation of the display surface, control and status activities, and identifying and changing 
the attributes associated with a device. 

Mixing access methods means opening a device using the Open function of one access method 
and then using the resulting opened device object to call operations of another access method. 
The extent to which access methods can be mixed is device dependent Character display I/O 
can generally be mixed with byte-stream I/O and record I/O. 

IV-5.1 .2 The Frame Buffer 

To manipulate characters on the device's two-dimensional display surface, an application 
program performs operations on a conceptual entity called timeframe buffer. The frame buffer 
is a two-dimensional grid of character cells whose contents are displayed on the surface of the 
device by a device-specific implementation of Char act er_Display_AM . Ops. 

On character and graphics terminals, for example, part of the frame buffer is visible through a 
rectangular area of the terminal screen called a window. The visible part of the frame buffer is 
caUed the view. Figure IV-5-1 depicts these relationships. 

For more information on windows, views, and frame buffers, see Chapter IV-4. 
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Figure IV-5-1. Views, Windows, and Frame Buffers 



The mechanism for specifying the dimensions of a frame buffer is device-dependent Calling 
Window_Ser vices . Ops . Create_window, for example, sets the dimensions of the 
frame buffer as well as the desired size and position of the corresponding view and window. 

On a character terminal, each cell in the frame buffer contains a displayable ASCH character, 
on a graphics terminal, each cell is measured in pixels and has a fixed width and height In 
both cases, cells are identified by their (column,row) coordinates, starting with (1,1) in the 
upper left-hand comer of the frame buffer and increasing downwards and to the right. Note 
that the column coordinate comes first in the coordinate pair. 

Figure IV-5-2 shows the frame buffer's coordinate system. 
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Figure IV-5-2. The Frame Buffer Coordinate System 



A cursor is used to identify specific cliaracter cells within the frame buffer. For example, the 
Write procedure writes characters at the cursor's current location and moves the cursor to a 
new location. Insert_char inserts characters at the cursor's current location and moves 
trailing characters to the right. Move_cursor_absolute and 
Move_cur sor_relative move the cursor without affecting the display. 



IV-5.1.3 The Output Model 



To write characters to the current cursor location in the fi-ame buffer, an application uses the 
Write procedure. Printable characters are written and the cursor is moyod forward, while 
control characters are either discarded, printed as <Ctrl-X>, or given special treatment. Note 
that writing to location (x,y) in the frame buffer overwrites the previous contents of that loca- 
tion. 

To insert characters at the current cursor location in the fi-ame buffer, an application uses the 
In sert_char procedure. Printable and control characters are treated as in Write. Trailing 
characters are moved to the right (and off the edge of the fi^ame buffer if necessary). 



IV-5.1.4 The Input Model 



Input is obtained with the Read call. Read is not supported by output-only devices, such as 
print devices. 

Input is classified according to the type of input event it represents. 
Terminal_Def s . input_enum emunerates the input event types, and 
Terminal_Def s . input_type_mask specifies which input event types are currentiy ac- 
cepted for a device. 
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Note that input events are not related to the event types discussed in the Event_Mgt package. 
The following is a list of the input event types: 

• keyboard 

• mouse 

• menu_item_picked 

• focus_changed 

• overlap_changed 

• size_changed 

• view_changed 

• position_changed 

• close_requested 

• scroll_requested 

• user defined 



This input model has a number of important features: 



• The Read procedure blocks until input arrives (if blocking is requested), and then returns 
input data. 

• Input fix)m aU sources is merged into one stream. This preserves the time-ordering of input 
events, which is crucial to applications where keyboard input describes something to be 
drawn at the current mouse position. 



• 



Although input from different sources is merged into one stream, contiguous sequences of 
input events fix)m different sources are retumed separately; that is, a call to Read returns 
only one type of input event. For example, if the input buffer for a device currently con- 
tains 7 keyboard characters, 2 mouse events, and 23 more keyboard characters, then three 
successive requests to read 80 bytes of input data wiU return, in succession, 7 charaaers, 2 
mouse events, and 23 characters. Because different types of input events are not inter- 
leaved within a single read, the application does not have to parse the input stream to 
separate the input events. 

Because Terminal_Def s . input_type_mask determines which input event types to 
accept, unwanted input is discarded at the earliest possible time. 

The application can change the set of accepted input event types at any time by changing 
Terminal_Def s . input_type_mask, but caution is important when doing so. For 
example, suppose the current input mask accepts only keyboard input. Then suppose that 
the application decides to accept mouse input, notifies the user of this, and changes the 
input mask accordingly. If the user manipulates the mouse before the application changes 
the input mask, mouse events may be lost. The application can avoid this by initially 
setting the input mask to accept both keyboard and mouse events, and then discarding the 
mouse events when they are not meaningful. 

Traditional keyboard-only input looks like simple byte-stream input. By default, keyboard 
input is the only type of input accepted for a new device. An application can obtain 
keyboard input for a device by calling the Read procedure in Byte_Stream_AM . Ops, 
Record_AM . Ops, or Character_Display_AM . Ops. 
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IV-5.1.5 Window Attributes 



A set of attributes is defined for each window on a terminal. These attributes affect the I/O 
operations performed in the window. Table IV-5-1 lists the attributes and their suggested 
defaults. 

See Terminal_Def s . window_attr for detailed information about the affect of these 
attributes. 

Window attributes can be queried and set using the following Terminal_Admin . Ops caUs: 

• Get_Terminal_Attr 

• Set_Terminal_Attr 

Table IV-5-1. Window Attributes 



Attribute 


Default Setting 


font.index 


1 


backgnxind ccAot 


daric (color intensities all 0) 


text_oolor 


white (color intensities all ordinal'last) 


map_<wit_LF_to_CRLF 


trae 


inap_out_CR_to_LF 


true 


scrcdl 


trae 


linewrap 


trae 


map_contiol_chars 


trae 


filLis.DEL 


false 


track_cursor 


false 


optimize_output 


trae 


enable.signal 


trae 


line.editing 


trae 


mouse_sampling 


buttoq_sampling 


echo 


trae 


echo_erase 


trae 


echo_LP_cancel 


trae 


no.flush 


false 


ignore_m_CR 


false 


map_in_CR_to_LF 


trae 


map_in_LP_to_CR 


false 



I V-5.1. 6 Operations 

The calls in Character_Display_AM . Ops fall into six logical groups: 
• Input 

- Get_input_type_mask 

- Set_input_type_mask 

- Read 
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- Enable_input_notif ication 

- Disable_input_notif ication 

- Discard_input 

• Output 

- Write 

- Insert_char 

- Flush 

- Discard_output 

- Ring_bell 

• Cursor Movement 

- Get_cursor_position 

- Move_cursor_absolute 

- Move_cursor_relative 

• Display 

- Clear 

- Clear_to_bottom 

- Clear_to_end_of_line 

- Delete_char 

- Delete_line 

- Insert_line 

• Control and Status 

- Open 

- Close 

- Is_open 

- Get_device_object 

- Get_device_info 

- Begin_batch_changes 

- End_batch_changes 

• Attributes 

- Get_enhancement 

- Set_enhancement 

- Set_region_enh an cement 

- Font list 
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IV-5.2 Techniques 

This section shows you some techniques for using Char acter_Display_AM .Ops: 

Opening a window 

Qearing the frame buffer 

Writing to the frame buffer 

Moving the cursor to an absolute position 

Moving the cursor relative to its current position 

Reading input events 

Inserting characters 

Deleting characters 

Identifying the underlying device. 

These techniques arc shown through excerpts from the Simple_Editor_ex procedure. 
Simple_Eciitor_ex is a simplified screen editor allowing the following operations on an 
ASai text file: 

Moving the cursor forward one column 
Moving the cursor back one column 
Moving the cursor up one row 
Moving the cursor down one row 
Paging up by the size of the view 
Paging down by the size of the view 
Deleting a character (forward) 
Deleting a character (backward) 
Inserting text 
Saving the edited file 
Quitting the editor. 

Appendix X-A contains a complete listing of Simple_Editor_ex. 

Because of the nature of this example, these techniques are oriented toward windows and 
terminals. 



IV-5.2.1 Opening a Window 



After reading the file to be edited into a buffer and creating a window in which to do the 
editing, the editor needs to open the window: 

870 — Open the edit window 

871 open_edit_window := Charact er_Display_AM. Ops. Open ( 

872 device => edit_window, 

873 input_output => Device_Def s. inout, 

874 exclusive => true) ; 
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edit_window is the device returned by a call to 

Window_Ser vices . Ops . Create_window. 

The other two parameters indicate that the window is to be opened for both input and output, 
with exclusive access. 

IV-5.2.2 Clearing the Frame Buffer 

The editor's next task is to clear the frame buffer and move the cursor to the (1,1) position: 

876 — Clear window on terminal screen. 

877 Character_Display_AM. Ops. Clear (open_edit_window) ; 

The opened_edit_window is the opened device returned by the earlier call to Open. 

Related calls clear the frame buffer from the current cursor position to the end of the line 
(Clear_to_end_of _line) and fiDm the current cursor position to the end of the window 

(C 1 e ar_t o_bo 1 1 om). 

IV-5.2.3 Writing to the Frame Buffer 

Next, the editor needs to display the file in the window. The Write operation writes charac- 
ters to the frame buffer (overwriting its previous contents) and leaves the cursor after the 
written data: 

879 — Write from edit buffer to frame buffer. 

880 — NOTE: There cannot be more line_feeds in the length 

881 — of characters written than there are rows in 

882 — the frame buffer, otherwise some of the first 

883 — characters will be overwritten in the frame buffer 

884 — The last line is written up to the line feed to 

885 — avoid having a blank line at bottom of the window 

886 Character_Display_AM.Ops.Write{ 

887 opened_dev => open_edit_window, 

888 buffer_VA => edit_buffer. lines 'address, 

889 length => System. ordinal ( {last_column * (frame_rows - 1)) 

890 + {Last_char_in_row(frame_end) - 1))); 
891 

edit_buf f er . lines' address is the address of the beginning of the buffer. 

The formula for the length parameter writes up to, but not including, the linefeed in the last 
line that the frame buffer will write. If the last linefeed is written the first line of the frame 
buffer will be overwritten and the last line of the frame buffer will be blank. 

IV-5.2.4 Moving the Cursor to an Absolute Position 

Since the write operation leaves the cursor after the last character, the editor needs to move the 
cursor to the (1,1) position by calling Move_cursor_absolut e: 

893 — Home the cursor (1,1 position). 

894 Character_Display_AM.Ops.Move_cursor_absolute ( 

895 opened_dev => open_edit_window, 

896 new_pos => origin) ; 

This procedure is called absolute because the new cursor coordinates specify an absolute loca- 
tion within the frame buffer. That is, calling the procedure with coordinates (x,y) moves the 
cursor to column x and row y of the frame buffer. (Column numbers increase to the right; row 
numbers increase downward.) 
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IV-5.2.5 Moving the Cursor Relative to its Current Position 

Cursor movement may also be relative to the cursor's current location in the frame buffer. For 
example, the following call moves the cursor forward (to the right) one column by assigning 
the value 1 to the parameter delta_col: 

272 Character_Display_AM.Ops.Move_cursor_relative ( 

273 opened_dev => open_edit_window, 

274 delta_col => 1, 

275 delta_row => 0); 

Assigning -1 to delta_col would move the cursor backward (to the left) one column, and 
assigning 1 (-1) to delta_row would move the cursor down (up) one row. 

lV-5.2.6 Reading input Events 

The default input mask is for keyboard input so a call to read is all that needed for input. 

908 procedure Handle_input 

909 

910 is 

911 

912 event_num: System. ordinal; 

913 event_type: Terininal_Defs. input_enum; 

914 char_buffer_AD: char_array_AD := new char_array' (others => ' '); 
915 

916 begin 
917 

918 — Enter the basic read and process loop 

919 loop 

920 — Read the next input event 

921 — default input mask is keyboard 

922 Character_Display_AM. Ops. Read ( 

923 opened_dev => open_edit_window, 

924 buffer_VA => char_buffer_AD. all' address, 

925 max_e vents => 1, 

926 max_bytes => 0, 

927 block => true, 

928 type_read => event_type, 

929 num_read => event_num) ; 

930 case event_type is 

931 when Terminal_Defs. keyboard => 

932 -- . . . 

933 key_input (char_buf f er_AD ( 1) ) ; 

934 when Terminal_Defs.menu_item_picked => 

935 — . . . 

936 key_input (char_buf fer_AD <1) ) ; 

937 when others => 

938 null; 

939 end case; 

940 end loop; 

941 end Handle_input; 

Setting the maximum number of events (max_e vent s) to 1 and the maximum number of 
bytes (max_bytes) to ensures that exactly one event wiU be read. The procedure blocks 
until input is available, and returns the number and type of the event in event_type and 
event_num respectively. 

char_buf f er_AD . all ' address is the address of the buffer in which the input events 
will be placed. 
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lV-5.2.7 Inserting Characters 

The following code inserts a character at the current cursor location in the frame buffer. 

535 — Insert the character in the frame buffer 

536 — (Frame buffer cursor is moved automatically) 

537 Character_Display_AM.Ops. Insert_char ( 

538 opened_dev => open_edit_window, 

539 buffer_VA => insert_char' address, 

540 num_char => 1); 

Unlike Write which overwrites characters, Insert_char pushes trailing characters to the 
right and leaves the cursor at the end of the inserted string. Characters pushed off the edge of 
the frame buffer are lost. 

iV-5.2.8 Deleting Characters 

The following code deletes a character from the frame buffer. 

382 — Delete the character from the window. 

383 Character_Display_AM.Ops.Delete_char ( 

384 opened_dev => open_edit_window) ; 

Note that the number of characters deleted can be specified (here it defaults to 1) and that 
deletion starts at the cursor*s current location. Trailing characters on the line are moved to the 
left, and new space at the end of the line is cleared to the current background color. 

IV-5.2.9 Identifying the Underlying Device 

To create a new window fix)m an old window, the editor obtains a reference to the device 
underlying the old opened window by calling Get_device_ob ject: 

837 — Create new window from old opened window. 

838 old_window := Character_Display_AM.Ops. 

839 Get_device_object {Process_Mgt .Get_process_globals_entry { 

840 Process_Mgt_Types .standard_input) ) ; 

841 under lying_terminal := Window_Services.Ops. 

842 Get_terminal (old_window) ; 

84 3 edit_window := Window_Services.Ops.Create_window( 

84 4 terminal => underlying_terminal, 

84 5 pixel_units => false, 

84 6 fb_size => Terminal_Def s.point_info' ( 

847 last_column, frame_rows), 

848 desired_window_size => Terminal_Defs.point_info' ( 

849 last_column,- preferred_window_rows) , 

850 window_pos => origin, 

851 view pos => origin); 



IV-5-3 Summary 



• 



• 



• 



The Character_Display_AM package is used for doing I/O to character display 
devices. Common examples of such devices are printers and windows on character and 
graphics terminals. 

To manipulate characters on the device's display surface, an application program performs 
operations on a frame buffer, a two-dimensional grid of character cells. 

The operations defined for character display devices fall into six groups: input, output, 
cursor movement, display, control and status, and attributes . 

Both input and output are defined for windows, but input is not defined for devices like 
printers. Input is implemented through a Read procedure that uses an input mask to 
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Specify which types of input events are accepted. Output is implemented through the 
Write and Insert_char procedures. 

Cursor movement operations and output operations occur within the frame buffer. Each 
(x,y) location in the frame buffer specifies a character cell that contains a displayable ASCII 
character. 

Display operations alter the appearance of the display surface. There are several operations 
to clear the display. 

The attribute operations query and set the attributes of a device. 

The control and status operations perform basic activities like opening and closing devices. 
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IV-6.1 Concepts 



This chapter describes spooled and direct printing. 

Packages Used: 

Spoo l_De f s Declares types and constants used by spooling packages. 

Spool__DeviceJMgt 

Manages spool devices. 

Spoo l_Queue__Adini n 

Provides administrative calls for spool queues. 

Pr inter_Admin Provides administrative operations for printers. 



A spool queue, which is required for all printing, is usually installed at system configuration. 
k print device is created by an application for printing. The print device is opened by an 
access method. If the print device is opened in spooled mode, the application's output is 
written to a spool file to await printing. Printing also requires an opened printer. See Figure 
IV-6-1. 
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Figure IV-6-1. Spooled Printing 



Output attributes, optional capabilities and basic printing and spooling functions can be con- 
trolled through the procedural interface. 
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IV-6.1.1 Spool Queue 



A spool queue is required for all printing. A spool queue contains spooled files, printer 
properties and capabilities, spooling properties, and a list of connected printers. Printer 
devices arc created in association witii a specific spool queue. 



IV-6.1.2 Print Device 



A print device is a device created by an application througli which data is spooled or printed. 
A print device must be created before writing a spool file or printing directly and is associated 
with a specific spool queue. It contains information specific to the print job including whether 
the print mode is spooled or direct. 

The lifetime of a print device is limited by the application which created it The application is 
responsible for explicitly deallocating the print device. The same instance of a print device can 
be used for several opens, writes and closes. 



IV-6.1.3 Spooled Printing 



A print device may be opened in spooled or direct mode. Spooled is by far the more com- 
monly used mode. When the mode is spooled, output is written to a spool file which is 
attached to the spool queue. The point at which the spool file is printed depends on: 

• Its position in the rank (relative position) of spool files for the spool queue, 

• The priority of the spool queue compared to other spool queues, and 

• Whether the spool file's rank is changed by moving it to another rank position, to another 
spool queue or by deleting it before it prints. 



IV-6.1.4 Direct Printing 



A print device may be opened in direct mode. Generally this mode is infi^quently used, 
usually chosen when printed information is urgently required. As with spooled mode, direct 
mode is controlled by the spool queue. The difference is that printing is written directly to a 
printer rather than to a spool file. 



IV-6.1.5 Spool File 



When a print device is opened for spooled printing, an Open call creates a new spool file. 
Write caUs send data to a spool file. 

Close readies the spool file for printing and allocates it in first in, first out order on its spool 
queue. The spool file is then printed when it reaches the top of the spool file rank and one of 
the printers connected with the spool queue is ready. 



IV-6.1.6 Printer Lists 



Lists of printers available for spooled and direct printing are maintained in spool queues, print 
devices and spool files. A member of a printer list is free for printing if it is not already 
engaged in printing and has the required fonn type mounted. 

When a print device is created for a spool queue, the print device inherits the complete printer 
list of the spool queue. This list may be modified but must be a fiill set or subset of the spool 
queue's list. The print device's printer list is inherited by its spool files. 
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A printer's connection with a spool queue is not exclusive. One spool queue may be connected 
with several printers, and one printer may be connected with several spool queues. In the latter 
case, the spool queuQ priority determines the order in which competing spool queues will gain 
use of a single printer to which they are connected. In direct printing, spool queue priority is 
not evaluated. The spool service simply uses the requested printer if it is available. 

IV-6.1.7 Print Area and Print Position 

The print area defines the area on a sheet or form where output may be printed. Characteris- 
tically, the print area wiU be less than the physical size of the page, being indented from the top 
and left side of the physical page. The print position is the location within the print area where 
printing will next commence. The initial print position for character output is top and left 
(column 1, line 1). See Figure IV-6-2. 



Initial 
print 
position 




Figure IV-6-2. Print Area 



IV-6.1.8 Requesting Form Type and Sheet Size 

Applications whose output must print on a certain form or specific size of sheet may request 
that the needed form or sheet be mounted before printing. The request may be one of three 
kinds: 

none - No form or sheet requirements 

form - Name of a form 

sheet - Size of (plain) sheet required. 

If a form or sheet is specified, print or spool service wiU prompt for acknowledgement that the 
requested form or sheet size is mounted before printing. 
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IV-6,1.9PrIntinfo 



Printinfo entries contain printer capabilities corresponding to sl printer type (printers with the 
same capabilities). The entries in the printinfo denote, for example, whether the printer sup- 
ports colors, and what bytes trigger corresponding functions, such as the bytes that make the 
printer print in red. A spool queue contains a printinfo reference which is specified when the 
spool queue is installed. 

When a printer is connected to a device, the printer's actual capabilities arc checked against the 
capabilities in the printinfo entry associated with a spool queue. The capabilities associated 
with the printer must be equal to or be a superset of the capabilities referenced by the printinfo 
associated with the spool queue. If this requirement is met, spooled and direct printing and 
printer emulation can be supported on a specific printer. 



IV-6.1.10 Print Properties 

Print properties are maintained in spool queues, spool files, and print devices. These 
properties include: 

• Device status 

• Termination message description and enable/disable status 

• Banner description and enable/disable status 

• Spool file deletion enable/disable status 

• Print copy count 

• Printer list. 

These properties can be set and queried. A Close call disconnects the spool file from the 
print device. Therefore, to modify or inquire about the properties of a spool file, the inquiry 
caUs should be made to the spool file instead of the print device. Also, deleting a spool file 
does not affect an existing print device for which the spool file has been created, and vice 
versa. 

IV-6.1.11 Implementation of Spool Device Attributes 

Spool device is a collective term applied to the following objects: spool queue, print device, 
spool file, dind printer. Table 1-1 defines the availability of spool device attribute implemen- 
tations among the various spool devices. "X" indicates that the attribute(s) is available for the 
indicated spool device, "XS" indicates that the attribute is only available for a print device 
when it is opened in spooled mode, and "- " indicates that the attribute(s) is not available for 
the indicated spool device. 
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Table IV-6-1. Implementation of Spool Device Attributes 





SPOOL DEVICE 


Spool_Device_MgtOps. calls 


print device 


spool file 


spotA queue 


printer 


Get_operation_sapport 

Get_acce88_method_siq>poit 

Get_device_statas 

Is_graiMcs_device 

Get_standanl_character_size 


X 


X 


X 


X 


Get_parain^er_text 

Set_panuneter_text 

Get_print_area_i)osition 

Get_print_area_size 

Is_pixel_unil8 


X 


X 


- 


- 


Get_prmter_list 

Coanect_printer 

Disconnect_prmter 

Getjenniiiatioo.message 

Set tennination_message 

Is tennination message.enabled 

Enable_tenniiiation_tnessage 

Disable_tennmatic»i_message 

GetJ>anner_page_line 

Set_banner_page_line 

Is_banner_page_enabled 

Enable_baiiiier_page 

Disable_banner_page 

Delete_device 


X 


X 


X 


- 


Get request class 
Get_sheet_request 


X 


X 


* 


X 


Set_sheet_reqaest 


X 


- 


- 


X 


Is_printmg_enabled 
Eiiable_piinting 
DisaUejpn'nting 
Aboit_printing 


- 


X 


X 


X 


Get_coiy_number 

Set_copyjnumber 

Is_deleting_enabled 

Enable_deleting 

Disable_deleting 


xs 


X 


X 


- 


Set_test_priiit 


xs 


X 


- 


- 


Get_print_count 


- 


X 


- 


- 
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IV-6.1.12 Delayed Printing 

Printing can be explicitly delayed for a spool queue until a specified time or delayed until a 
specified time when the size of the print job exceeds a specified limit. Print delays are clas- 
sified as none for no delay, time for a timed delay, or size for a delay dependent upon the 
size of the spool file and the number of outstanding print requests. 

IV-6.1.13 Banner Page and Print Termination l\/lessage 

A banner page is an optional page which may be printed to identify a print job. A banner page 
consists of up to five lines. A print termination message is an optional message which may be 
sent to the user who created the print device to signal completion of a print job. 

The lines of banner pages and termination messages are defined by 

Incident__Def s . incident_code. Formal parameters $pl through $p5 may be used 

within message texts used to defined banner page lines and termination messages. Formal 

TM 

parameters are defined in the BUN Command and Message Guide. Each time a print device 
is created, these formal parameters are assigned the following defaults: 

$pl - The basename of the spool queue where the print device 
has been created. 

$p2 - The node on which the print device has been created. 

$p3 - Van job within which the print device has been created. 

$p4 - The time at which the spool file was created or the print 
device was opened for direct printing. 

$p5 - The user who created the print device. 

The formal parameters are updated when a spool file is created (spooled mode) or a print 
device is opened (direct mode). 

IV-6.1.14 Default Properties 

A new spool queue receives the following default properties: 



• 



Spool queue properties: 
Spooling is enabled 

The lowest spool queue priority is assigned 

No spool queue print delay is set. 

Print properties: 

No printers are connected 

Printing is enabled 

No multiple copies are requested 

Automatic deleting of printed spool files is enabled. 
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• Other properties: 

No banner page will be printed 

No printer termination message will be issued. 

A new spool queue receives the following default properties: 
Print mode is spooled 

Print position is (1,1). 



When a print device is created, it inherits the print properties of its associated spool queue. 
When a print device created in spooled mode is opened, the resultant spool file inherits the 
print device's print properties. The application may modify these print properties at any time 
between the creation of the print device and the time that the spool file begins to print. Print 
properties of a print device created for direct printing may be modified after the print device is 
created and before printing commences. Attempts to modify print properties after printing has 
commenced will fail. 



IV-6.2 Techniques 

After reading this section, you will be able to: 

• Print to a spool file 

• Print directly to a printer 

• Control print properties 

• Administer spool queues and printers 

• Add a new type of printer. 

The sample code segments are excerpted from the pr int_cmd_ex example package. Ap- 
pendix A contains a complete listing of this package. 

IV-6.2.1 Printing to a Spool File 

Calls Used: 

Spool_Device_Mgt . Create__print_device 

Creates a print device for a spool queue. 

Spool_Device_Mgt . Create_pr int_device_by_name 
Creates a print device for a spool queue. 

Spool_Device_Mgt . Ops . Set_copy_number 
Sets the number of copies to print 



The first step in sending output to a printer is to create sprint device. Then the print device is 
opened and the output is written to a spool file for spooled mode or to na printer for direct 
mode (via calls of an access method supported by the print device). The actual time that a 
spool file is printed depends on queue priorities and delays and printer availability. Output 



IY„5„g Printing 



PRELIMINARY 



written in direct mode is printed immediately if the requested printer is available, otherwise the 
write call must be reissued until the printer is available. 

In the following example, Spool_Device_Mgt . Great e_print_device is called to 
create a print device for spooled printing. pixel_units are set to false which causes the 
pr int_area to be interpreted as character cells. The print_area is set to 132 characters 
wide by 66 characters long. The print_mode defaults to spooled. The print device is 
then opened and written to with byte stream access method calls. 

After the print device is closed, the data is written to a spool file buffer to await an available 
printer or sent directly to a specific printer, depending upon the mode in which the print device 
was created. 

93 sheet_size: constant Spool_Defs.size_t := 

94 (132,66); 

139 on_untyped := Directory_Mgt .Retrieve {on_device) ; 

140 if Spool_Defs. Is_spool_queue(on_untyped) then 

141 print_device := 

142 Spool_Device_Mgt . Create_print_device ( 

143 spool_queue => spool_queue, 
14 4 pixel_units => false, 

145 print_area => sheet_size) ; 

160 open_print := Byte_stream_AM. Ops. Open { 

161 print_device, 

162 Device_Def s. output ) ; 
163 

164 while not 

165 Byte_Stream_AM.Ops.At_end_of_f ile (open_source) 

166 loop 

167 bytes_read := Byte_St ream_AM. Ops. Read { 

168 opened_dev => open_source, 

169 buffer_VA => buffer' address, 

170 length => buf fer_size) ; 
171 

172 Byte_Stream_AM.Ops.Write( 

173 opened_dev => open_print, 

174 buffer_VA => buf fer' address, 

175 length => bytes_read) ; 

176 end loop; 
177 

178 Byte_Stream_AM. Ops. Close (open_source) ; 

179 Byte_Stream_AM. Ops. Close {open_print) ; 

When the application issues a Close call, the printer is reallocated in the spool queue printer 
list and again becomes available for spooled or direct printing. 

The nimiber of copies of the spool file that will be printed defaults to 1 . The number of copies 
may be changed by calling Spool_Device_Mgt .Ops . Set_copy_nuniber with the 
desired number of copies. 

IV-6.2.2 Printing Directly to a Printer 

When a print device is created for direct printing (the print_mode parameter in 
Spool_Device_Mgt . Great e_print_de vice is set to page_wise or line_wise), 
an Open call establishes a direct connection with a printer from the print device's printer list. 

147 elsif Spool_Defs. Is_print_device(on_untyped) then 

148 print_device := 

14 9 Spool_Device_Mgt .Create_print_device ( 

150 spool_queue => spool_queue, 

151 pixel_units => false, 

152 print_area => sheet_size, 

153 print_mode => Spool_Defs.page_wise) ; 

154 — direct printing 
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IV-6.2.3 Controlling Print Properties 



Calls Used: 



Spool__Device_Mgt . Set jpage_output_attributes 
Sets page output attributes. 

Spool_Device_Mgt . Get_j>age_output_attributes 

Returns the page output attributes associated with a print device. 



These calls permit query and modification of page output parameters for a print device. These 
parameters include: 

• Line feed and carriage return mapping 

• Mapping of control characters 

• Scrolling 

• Linewrap 

• Print color (if the printer is capable of color). 

The first four parameters default to true and the print color defaults to black when a print 
device is created. The settings of these parameters can be queried and reset. 

The spool service and print service conform to the standard printing model in which: 

• Linewrap is set so that text is never lost. 

© Line feeds and carriage returns are mapped to the line feed/carriage return combination. 

• Control characters are printed as a two-character sequence (^<character>). 

• A page advance is performed when the current print position is in the last column of the last 
row. 

• Text color, if applicable, is set black. 

Table IV-6-2 lists other calls that control properties with brief descriptions of their uses: 
Table IV-6-2. Getting and Setting Print Properties 



Property 


How to Get and Set It 


Get the cunent print 
position and print area size. 


Spool Device Mgt.Ops.Get_print area position 
SpooinDevice^lgt . Ops . Get_print_area_si ze 


Set and check the completed 
number of copies of a print job. 


Spool Device Mgt.Ops.Set copy number 
Spool_DeviceTigt . Ops . Get_prinr_count 


Get a list of printers 
available for a spool queue, 
spool nie, or print device. 


Spool_Device_Mgt . Ops . Get_printer_li st 


Get a device's sheet request 


Spool_Device_Mgt . Ops . Get_sheet_request 


Get a device's diaracter size. 


Spool_Device_Mgt . Ops . Get_standard_character_si ze 


Chedc whether sizes are 
measured in pixels or 
character units. 


Spool_Device_Mgt.Ops.Is_pixel_units 


Get and set a spool queue's 
print delay properties. 


Spool Queue Admin .Get delay class 
Spool Queue Admin. Get print delay 
Spool Queue Admin. Set print delay 
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Property 


How to Get and Set It 


Get and set the priority 
assigned to a spool queue. 


Spool Queue Admin. Get priority 
Spool_Queue_Admin . Set^riori ty 


Get the request dass for a 
spool nie, printer, or print 
device. 


Spool_Device_Mgt.Ops.Get_request_class 


Get the printinfo associated 
with a spool queue. 


Spool_Queue_Admin.Get_printinfo 


Get and set a printinfo. 


Printer Admin. Get printer type 
Printer_Admin. Set_printer_type 



IV-6.2.4 Administering Spooi Devices 

Table IV-6-3 lists calls that inquire about and set the states of spool devices, enable and disable 
spool device capabilities, install a spool queue and move spool files. 

Table IV-6-3. Executing Print and Spool Tasks 



Task 


How to do it 


Check what spool device 
an AD references. 


Spool Defs.Is emulation 

Is print device 
Is_printer 
Is printinfo 
Is spool file 
Is_spool_queue 


Get and set the emulation 
in effect for a print device. 


Spool Device Mgt.Get emulation 
Set_emulation 


Get the output device for a 
print device (spool file for 
spooled printing or a printer 
for direct printing.) 


Spool_Device_Mgt . Get_output_device 


Get a print device's print mode. 


Spool_Device_Mgt . Get_print_mode 


Get a print device's 
associated spool queue. 


Spool_Device_Mgt . Get_spool_queue 


Stop and disable printing. 


Spool_Device_Mgt.Ops.Abort_printing 


Delete a spool queue, print 
device, or spool file. 


Spool_Device_Mgt . Ops . Delete_device 


Enable or disable automatic 
deletion of printed spool 
files. 


Spool Device Mgt. Ops. Enable deleting 
Spo o lT3e v i ceT^gt . Op s . D i s ab 1 e_de 1 e t i ng 


Enable or disable printing 
by a spool file, spool 
queue, or printer. 


Spool Device Mgt.Ops.Enable_printing 
Spool33eviceT<gt.Ops.Disable_printing 


Print or don't print a banner 
page, and set a banner page 
line. 


Spool Device Mgt .Ops. Enable banner page 
Spool~Device"~Mgt. Ops. Disable banner page 
Spool3'evice~Mgt .Ops.Set banner page line 


Set, print or don't print a 
termination message. 


Spool Device Mgt .Ops. Enable termination message 
Spool~Device~Mgt .Ops. Disable termination message 
SpooinJevice^Wgt • Ops . Set_termination_message 


Associate a fomial parameter 
with a text string. 


Spool_Device Mgt. Ops. Set parameter text 


Determine supported access methods. 


Spool_Device_Mgt . Ops . Get_access method_support 


Determine a spool device's status. 


Spool_Device_Mgt . Ops . Get_device_status 


Get a list of the attribute 
calls supported by a device. 


Spool_Device_Mgt . Ops . Get_operation support 


Qieck oiable or disable status. 


Spool Device Mgt. Ops. Is banner page enabled 
Is deleting enabred 
Is printing enabled 
Is_termina£Ton message_enabled 


Check whether a device 
supports graphics. 


Spool Device Mgt .Ops.Is_graphic device 
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Task 


How to do it 


Enable or disable spooling. 


Spool Queue Admin. Enable spooling 
Spool_Queue_Admin . Enable_spooling 


Get a list of spool files in 
print order. 


Spool_Queue_Admin . Get_rank_li st 


Install a spool queue. 


Spool_Queue_Admin. Install 


Determine if a spool queue 
contdns anv spool files, 
and if spo<uing is envied. 


Spool Queue Admin. Is empty 
Spool_Queue_Admin . I s_spooling_enabled 


Change the order of printing 
foraspodlfile. 


Spool_Queue_Admin . Modi f y_rank 


Move a spool file to another 
spool queue. 


Spool_Queue_Admin . Move_spool_f ile 



IV-6.2.5 Adding a New Printer 

Calls Used: 

Printer__Adinin . Set_printer_type 

Associates a printinfo with a printer. 

Spool_Device_Mgt .Ops .Connect__printer 

Connects a printer to a spool queue, or selects a printer from the spool 
queue's printer list to be stored in the printer list of a print device or spool 
file. 



The process of adding a new printer requires an existing printinfo for the type of printer to be 
added, and a printer object Then, the printer can be associated with its printinfo with 
Pr inter_Adinin . Set_pr inter_type, and the printer can be added to a printer list with 
Spool_Device__Mgt .Ops .Connect_printer. 

IV-6.3 Summary 

• A spool queue is an instance of a spool device class and is required for all printing. 

• A print job may be spooled or sent directly to a printer. 

• A print device must be created before writing a spool file or printing directly. 

• A print device opened in Spool_Def s . print_mode_t . spooled mode will send the 
print output to a spool file. 

• A print device opened in Spool_Def s . pr int_mode_t . line_wise or 
Spool_Def s . print_mode_t . page_wise mode will send the print output directly 
to a printer. 

• Printinfo entries contain printer capabilities corresponding to printers with the same 
capabilities. 

• Lists of printers available for spooled and direct printing are maintained in spool queues, 
print devices, and spool files. 

• The print area defines the area on a sheet or form where output may be printed. 

• The print position is the location within the print area where printing will next commence. 
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A banner page is an optional page which may be printed to identify a print job. 

A print termination message is an optional message which may be sent to the user who 
created the print device to signal completion of a print job. 

Applications whose output must print on a certain form or specific size of sheet may re- 
quest that the needed form or sheet be mounted before printing. 

Print properties are maintained in spool queues, spool files, and print devices. 

Printing can be explicitiy delayed for a spool queue until a certain time, or until a certain 
time if the size of the print job exceeds a limit. 
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This chapter is an overview of the concepts and tenninology for structured files. This chapter 
does not present any programming techniques. 

Packages Used: 

Data_Def inition_Mgt 

Manages field and record data definition (DDef) creation for structured 
files. 

Field_Access Provides buffer access to fields in records that reference DDefs. 

File_Admin Provides calls and declarations for managing structured files. 

File_Def s Provides declarations used for filing operations. 

Join_Interface 

Provides database support for joins of indexed files or record stream 
devices. This package is only available to trusted type managers. 

Record_AM Provides device-independent I/O for accessing records one record at a 

time. Contains the Record_AM . Ops and Record_AM . Keyed_Ops 
packages. 

Record_AM . Ops Provides a common interface for record I/O calls. 

Record_AM . Keyed_Ops 

Provides record VO calls for indexed files. 

Record_Processing_Support 

Provides calls for processing collections of records. 

Sort_Merge_Interface 

Provides calls for sorting and merging records. 

Trusted_Record_Processing_Support 

Provides calls for processing collections of records using user-supplied 
routines. This package is only available to trusted type managers. 



The following chapters explain more about using structured files: 

• Chapter IV-8 explains how to use the filing and record I/O calls to build indexes in struc- 
tured files. 

• Chapter IV-9 explains how to use record I/O to access structured files with indexes. 

• Chapter IV- 10 explains how to use locking to control concurrent access to structured files. 

• Chapter IV- 1 1 explains how to use the record processing and database support packages to 
process collections of records. 

These chapters further explain the concepts in this chapter, and present programming tech- 
niques for using them. 

IV-7.1 Stream Files and Structured Files 

The filing service provides two kinds of files: stream files and structured files. Stream files 
contain a stream of contiguous bytes and allow random byte access within file. You usually 
use byte stream I/O to read and write stream files. Stream files cannot have indexes. 
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Structured files contain a collection of records having a common structure. These files can 
have indexes and allow record positioning within the file. You usually use record I/O with 
structured files, for reading and writing records. 

This chapter describes structured files. Chapter IV-3 describes stream files. 



IV-7.1.1 Data Areas 



Files are represented by a. file object that can be accessed through difile AD. The file's contents 
reside in several data areas. A structured file has sl primary data area and can have one or 
more secondary data areas. Figure IV-7-1 shows a file AD to a structured file object with 
primary and secondary data areas. 



File Ad 




File Object 











Figure IV-7-1. File Objects and Data Areas 



A structured file has one primary data area, and it contains the file's data. A structured file can 
have up to 16 secondary data areas. Secondary data areas contain indexes. 



IV-7-2 Records 



Record are named collections of data haying fields to hold the data. Fields can contain any 
type of data except ADs. Records can have two formats: 

Fixed-length records 

Each field in the record has a fixed size. 

Variable-length records 

One or more fields in the record vary in size. 

A record has a size that you can specify when you create a structured file. The maximum size 
of a record can vary depending on your file organization. The maximum record size for 
records in sequential files is 16 megabytes. The record size is limited to the size of the bucket 
(minus the bucket overhead) for unordered, clustered, and hashed file organizations. 

Each record in a file has a record ID that provides access to the record's physical location in a 
file. A record gets a unique ID when it is inserted in a file. Record IDs can only change when 
the key value the file's organization index changes. You can get a record ID when inserting or 
reading a record. 

Records in relative files have a record number for quick record access. In a relative file, each 
record in the file has a fixed position with a corresponding unique number. When a record is 
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inserted in the file, the record receives a unique record niunber. This record number does not 
change. 



IV-7.3 Buckets 



The filing service divides the primary and secondary data areas of structured files into a num- 
ber of fixed-sized buckets. The filing service uses buckets to transfer records between active 
and passive store. A bucket can hold many records that can span across multiple buckets 
depending on the file organization. Some file organizations allow you to choose the bucket 
size. 



IV-7.4 Indexes 



Indexes provide fast access to structured files. An index can either be an organization index or 
an alternate index. An organization index defines the organization of the primary data for 
clustered and hashed files. When creating a file, you create an organization index which you 
cannot delete or deactivate while the file exists. An alternate index does not affect the or- 
ganization of the primary data area. After creating a file, you can add alternate indexes which 
you can destroy, deactivate, or reorganize at any time. Up to fifteen alternate indexes can be 
added to a hashed or clustered file. Up to sixteen alternate indexes can be added to a sequen- 
tial, relative, or unordered file. 

An index can have one of these structures: 

B'tree Uses a b-tree data structure to organize an index's record key values. 

Hashed Uses a hashing function to index records. 

B-tree indexes contain record key values in a b-tree. Searching for particular key values 
compares key values at each level of the tree until the correct key value is found. Key values 
map to record IDs that provide access to a specific record in the file's primary data area. This 
structure is particularly suited for indexed-sequential record access, for example, scanning all 
employee records fipom G through P. 

A hashed index uses a hashing function to index records. The hashing function lets you access 
any record in the file quickly, for example, reading a specific employee record. An indexed- 
random read typically takes one disk access with hashed indexes. Indexed-sequential reads are 
not possible using this index. 

Chapter IV-8 provides more information about using indexes with structured files. 



IV-7.5 Structured File Organizations 



Each structured file has a file organization that dictates how records are stored in the file. A 
structured file can have one of these organizations: 

clustered Records are organized in related groups (clusters) according to a clustering 

b-tree organization index. 

hashed Records are organized according to a hashed organization index. 

relative Records are organized in an array of fixed-size record slots. 
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sequential 
unordered 

IV-7.5.1 Sequential Files 



Records are organized in the sequence in which they are inserted. 
Records are organized according to available free space. 



A sequential file is a stream of formatted records where the logical and physical order of the 
records are the same. Figure IV-7-2 shows a sequential file. 
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Figure IV-7-2. Sequential File 



Sequential files do not depend on a termination character to read a record because the filing 
service already knows the structure of the record. Sequential files are efficient for serial or 
sequential processing of records, where you position reading and writing by retrieving the next 
record. Major characteristics of sequential files include: 

• You cannot delete records in sequential file. 

• You can update records as long as the updated record is the same size as the original record. 

• The filing service automatically inserts records at the end of the file (useM for history or 
log files). 

• Records can be indexed using up to 15 b-tree alternate indexes in separate secondary data 
areas. 

• The maximum record size in primary data is 16 megabytes. 

• Variable length records are not restricted to a bucket size. 

• Indexes are allowed. 

• There is no secondary data area unless the file has alternate indexes. 

• The primary bucket size is always 4 kilobytes. 



IV-7.5.2 Relative Files 



A relative file consists of a sequence of fixed-size record slots; each slot can be empty or can 
contain one record. Figure IV-7-3 shows a relative file. 
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Figure IV-7-3. Relative File 



Relative files let you randomly access a record by record number or record ID. This makes 
relative files more efficient for random access than sequential files. The characteristics of 
relative files include: 

• You can insert and delete records. 

• Records with varying lengths can change size only if the record does not exceed the size of 
the record slot. 

• You can access records by record number. 

• Indexes are allowed. 

• The primary bucket size is always four kilobytes. 

« You must explicitly handle free space for relative files. 



IV-7.5.3 Unordered Files 



An unordered file organizes records in the primary data area according to available fiee space. 
Figure IV-7-4 shows an unordered file. 
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Figure IV-7-4. Unordered File 



In unordered files there are no organization indexes; the system determines the record order- 
ing. Unordered files are for applications that require concurrent record inserts. 



The characteristics of unordered files include: 
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• Records can be deleted and updated. 

• Unordered files works well for files with records of varying lengths. 

• Favors concurrent record inserts. 

• The maximum primary record size is limited to the size of the bucket minus bucket over- 
head. 

• Unordered files pack variable-length records efficiently. 



IV-7.5.4 Clustered Files 



A clustered file organization provides fast indexed-sequential access to records. The organiza- 
tion index influences the placement of records in a clustered file. Figure IV-7-5 shows a 
clustered file. 
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Figure IV-7-5. Clustered File 



Records in the file's primary data area are clustered, meaning the filing service physically 
stores records with similar key values near each other. The characteristics of clustered files 
include: 

• Records can be inserted, updated, and deleted. 

• Updated records can change size. 

• Random access is allowed. 

• The organization index must be a b-tree index. (Note that the first index created on a file 
must be an organization index.) 



You can change key values in the organization index at any time. 
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• You can index records with up to fifteen alternate indexes. You define each alternate index 
in a separate secondary data area. 

• The maximum primary record size is limited to the size of the bucket minus any bucket 
overhead. 



IV-7.5.5 Hashed Files 



Hashed files are designed for indexed-random access via an organization key. Like a clustered 
file, the organization index influences the placement of records in a hashed file. Figure IV-7-6 
shows a hashed file. 
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Figure IV-7-6. Hashed File 



In a hashed file organization, the filing service stores records and keys in the file's primary 
data area; there is no secondary data area. The filing service organizes a hashed file using a 
hashing fimction that produces hashed values for record positioning in the primary data area. 
The characteristics of hashed files include: 

• Records can be inserted, updated, and deleted. 

• Updated records can change size. 

• The organization index must be hashed. 

• Random reads via the organization key usually require only a single disk access. 

• Index-sequential access via the organization key is only possible for reading duplicate se- 
quences. 

• The maximum primary record size is limited to the size of the bucket minus bucket over- 
head. 



IV-7.5.6 File Descriptors 



File descriptors contain information about a file's logical and physical characteristics. There 
are three possible descriptors for a file: 

Logical file descriptor 

Contains options for selecting a structured file's record formats, record 
DDefs, transaction locking, and logging. See the File_Admin package 
for the logical file descriptor record. 

Physical file descriptor 

Contains information about a structured file's volume layout. See the 
File_Adinin package for the physical file descriptor record. 
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Index descriptor 



Contains information for an index in a structured file. A file can have 
several indexes and several index descriptors. See the File_Def s pack- 
age for the specification of the index descriptor record. 



You must use a logical file descriptor to create a file, but you only use a physical file descriptor 
to control the file's disk space and volume set allocation. You use index descriptors to create 
indexes in a file. 



IV-7.6 Using Byte Stream and Record I/O with Files 

You normally use byte stream I/O to access stream files and record I/O to access structured 
files. But structured files support byte stream and record I/O. Table IV-7-1 summarizes the 
differences between stream and structured file access. 

Table IV-7-1. Accessing Stream and Structured Files 





By t e_S t re am_AM 


Record_AM 


Stream 


Read and write bytes 


Termination character appended 
during insert Read reconi up to next 
termination character. 


Structured 


Read bytes of a record. 
No writes allowed. 


Read and insert records. 



With stream files, you can read or write the entire contents of the file. Using byte stream I/O, 
you can read but not write structured files. This protects against inadvertent modification of 
the file's record structure. When reading a structured file using byte stream I/O, all internal 
control information and deleted records are filtered out. 

You usually use record I/O to access a record-oriented device such as a file, pipe, or directory 
one record at a time. There are four record access modes: 

physical-sequential Sequential access according to the physical sequence of records in the file. 

physical-random Random access to records using physical positioning. 

indexed-sequential Sequential access to an indexed file in key sequence starting with any key 
value in an index. 

indexed-random Random access to records according to a record's key value. 

You only use physical-sequential and physical-random modes to access structured files that do 
not have indexes. You can use any access mode to access structured files with indexes. Table 
IV-7-2 shows access modes for files. 

Table IV-7-2. File Access Modes 





Stream 


Seqential 


Relative 


Unordered 


Qustered 


Hashed 


Physical-Sequential 


X 


X 


X 


X 


X 


X 


Physical-Random 


X 


X 


X 


X 


X 


X 


Index-Sequential 
(Organization Lidex) 










X 


X 


Index-Sequential 
(Altemate Lidex) 




X 


X 


X 


X 


X 


Index-Random 
(Organization Index) 










X 


X 


Index-Random 
(Altemate Index) 




X 


X 


X 


X 


X 
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Chapter IV-9 discusses in more detail how to accessing files with record I/O. 

IV-7.7 Structured Files and Transactions 

Transactions can lock indexes, records, and structured files to synchronize concurrency during 
file access operations. Chapter IV- 10 provides information about locking structured files. 

IV-7.8 Summary 

• Structured files are collections of records having a similar structure. 

• You usually use record I/O to access structured files. 

• The filing service always stores a file's data in a primary data area. 

• Records are named collections of data hsLwing fields to hold the data. 

• Indexes provide fast access to records in files. 

• Organization indexes influence the placement of records in the primary data area. 

• Alternate indexes do not influence the placement of records in the primary data area, and 
are optional for aU structured file organizations. 

• Structured files can be indexed with either b-tree or hashed indexes. 

• The filing service provides five structured file organizations. Each structured file organiza- 
tion has characteristics that make them suitable for particular applications. 

• There are three descriptors that can be defined for a file: logical, physical, and index. 
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This chapter provides the concepts and techniques for managing structured files and indexes. 

Packages Used: 

File_Def s Provides declarations for filing and indexing. 

File_Admin Administers files. 

Data_Def inition_Mgt 

Manages the data definitions (DDefs) for creating records, fields, and in- 
dex keys. 



IV-8.1 Concepts 



Indexes provide fast access to records in structured files. To create an index, you define its 
structure and key definition. You use DDefs to define an index structure and the index key 
definition. Figure IV-8-1 shows an index for a file. 
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Figure IV-8-1. An Indexed File 



The index has a b-tree organization, is located in the secondary data area of the file, and uses 
key values to reference records in the primary data area. 



IV-8.1. 1 Index Keys 



Within an index, you can define particular record fields as keys. Keys let you identify par- 
ticular records, order records in a file, or specify records you want to retrieve or update. You 
can order records in a key by ascending or descending order based on the key value in each 
record. Keys are efficient for reading and retrieving records in a file, but are less efficient for 
inserting updating, and deleting records. 
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If a key value uniquely identifies a record, the key is sl primary key. For example, the name 
key for an employee record uniquely identifies an employee. Keys whose values do not 
uniquely identify a record are secondary keys. For example, the key dept in an employee 
record does not uniquely identify an employee record. Figure IV-8-2 shows a representation of 
an index with key values. 
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Figure IV-8-2. Index Key Values that Point to Records 



The calls in the Record_AM . Keyed_Ops package provide specific keyed operations for 
indexed access to structured files. 



IV-8.1.2 Index Structures 

There are three index structures: 



B'tree alternate indexes are located in secondary data areas of structured files. These 
indexes do not affect the file organization. 

B'tree organization indexes organize records in the primary data area based on the sort 
sequence of an organization key. 

Hashed organization indexes organize records in the primary data based on a hash function 
that determines the record locations. 



IV-8.1.2.1 B-Tree Alternate Index 



You can build b-tree alternate indexes on any structured file B-tree alternate indexes do not 
reorganize a file, which means you can delete or deactivate them without destroying the file. 
These indexes support fast sequential access and moderately fast random access. Figure 
IV-8-3 shows a b-tree alternate index. 

B-tree alternate indexes: 

• Exist in the secondary data area 

• Contain record key values in the b-tree structure. 
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Figure IV-8-3. B-Tree Alternate Index 



IV-8.1.2.2 B-Tree Organization Index 

A b-tree organization index is used to organize clustered files. You can only delete or deac- 
tivate a b-tree organization index by destroying the file. Figure IV-8-4 shows a b-tree or- 
ganization index for a clustered file. 
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Figure IV-8-4. Clustering B-Tree Organization Index 
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B-txee organization indexes: 

• Have buckets that contain the key portion of the record 

• Are not strictly sorted 

• Indexed-sequential access via the organization key is very fast for large scans. 

IV-8.1.2.3 Hashed Organization Index 

You use hashed organization indexes with hashed files for fast random access to key values. 
Figure IV-8-5 shows a hashed organization index for a hashed file. 
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Figure IV-8-5. Hashed Organization Index 



Hashed organization indexes: 

• Only uses the primary data area. 

• Uses a hashing function to provide quick access to any record in the file. 

• Except for duplicate key values, are not accessible via indexed-sequential access. 

• Do not reorganize the primary data area of hashed files. 

lV-8.1.3 Choosing Indexes 

Table IV-8-1 lists index performance considerations by application type: 
Table IV-8-1. Index Performance Considerations 



Application 


B-Tree 

Alternate 

Index 


Clustered 

B-tree 
Org Index 


Hash 
Org Index 


Full-ordered scan 

in sorted order 

- employees G to T 


Good 


Excellent 


Not 
available 


Online random access 
— employee 
Albeit Einstein 


Satisfactory 


Satisfactory 


Excellent 


Update-intensive 
-Key value changes 


Satisfactory 


Poor 


Satisfactory 


Insert-intensive 


Satisfactory 


* 


Satisfactory 



In a b-tree index for a clustered fde, insert-intensive operations cause the average access time to degrade c^er the 
initial reserved space is used up (if the proper fill-factor is selected), and after initial loading or reorganization. 
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IV-8.1.4RecordDDefs 



You use data definitions (DDefs) to define the data layouts for structured files. If you want to 
use indexes, you must use DDefs. Record DDefs specify a complete DDef for a record. You 
can usQ field DDefs to specify each record field so you can logically group the field DDefs to 
create record DDefs. Field DDefs have the advantage that you can reuse them to create other 
record DDefs in your application. You define record and field DDefs using the 
Data_Def inition_Mgt package. 



NOTE 

If you do not use DDefs for record layouts, you have to maintain your own record layout. 
(Ada users use record types; C users use structures.) The filing service does not restrict 
using a single field for multiple keys, overlapping fields, or having the same record por- 
tion appear in different fields with different field types. 

Before creating a structured file, you create a record DDef that defines the file's record struc- 
ture. The record DDef includes the record's: 

• Alignment 

• Size 

• Field data types. 

Figure IV-8-6 shows a record DDef for an employee file. 
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Figure IV-8-6, A Simple Record DDef 
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In this figure, the DDef consists of several nodes including: 

• A root node that represents the DDef corresponding to a record with fields 

• The non-root nodes that represent the record's fields. 

To create a DDef node, you create the node and add property values to the node. A node's 
property values include the node's size, length, and data type. 

To create a record DDef, you use the Data_Def inition_Mgt calls in the following order: 

1. Make a Great e_DDef call to create a DDef object. 

2. Make a Create_node call specifying metatype = record to create a DDef node 
inside the DDef object. 

3. Define a DDef field. 

a. Make a Create_simple_f ield call to create the field. 

b. Make an Add_j5roperty_value call to define the property values for the field. 
Repeat this step until all the DDef fields are created. 

4. Make a Close call to close and bind the DDef. 

When you create a record DDef, you can derive the DDef from individual field DDefs. You 
can also define a record layout to ensure that the record DDef and the record layout cor- 
respond. You do this using an Ada representation clause. See section IV-8.2 for examples of 
setting up record DDefs. 

You use DDef _specif led field in a logical file descriptor to specify the record DDef that 
defines a structured file's record layout. See the Data Def initon Mgt package in the 

TM "^ """ 

BUN /OS Reference Manual for more information about DDefs. 



IV-8.1 .5 Index Key DDefs 



The index key DDef defines the record fields that make up a key value for a structured file. An 
index key DDef describes either: 

• A single key built on a single field (for example, the Dept key has one field, department) 

• A composite key built on two or more fields (for example, the Dept_Salary key has two 
fields, department and salary). 

You can use index key DDefs to specify whether values for an index field are sorted in ascend- 
ing or descending order. For example, the department field could be sorted in ascending order 
from department 1 to department 500, and the salary field could be sorted in descending order 
fi-om 10, 000 to 1,000. An index key DDef can take one of two forms: 

Derived The index key DDef is derived from a record DDef. 

Non-derived The index key DDef is created separately. 

Figure IV-8-7 shows an index key DDef built on the department field in an employee file. 
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Figure IV-8-7. A Simple Derived Index Key DDef 



You can derive an index key DDef from one or more of the record DDef s nodes, using the 
Data_Def inition_Mgt calls as follows: 

1. Make a Create_DDef call to create a new DDef object This DDef is separate from the 
record DDef. 

2. Make a Create_node call to create a record DDef node inside the DDef object. 

3. Derive a DDef field from the record DDef. 

a. Make a Create field call to create tiie field. 
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b. Make an Add_property_value call to define the property values for the field. 

These calls create a field DDef node that references your existing field definitions (in the 
record DDef used for your file's record layout). 

Repeat this step until all the DDef fields are created for your index key. 

4. Make a Close call to close and bind the DDef. This computes field sizes and positions. 

Figure IV-8-8 shows the layout of a record DDef and an index key DDef from the record 
DDef. 
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Figure IV-8-8. Layout of a Derived Index Key DDef 



NOTE 

The filing service adds the padding in the record layout for proper alignment of the 
record fields. The index key DDef uses the same image as the record DDef. 



IV-8.1.6 Null Values 



A null values is the highest possible value you can give a field. You can use null values to 
write efficient queries, because the filing service groups all keys with null values together. 
This provides a faster search algorithm for these fields. For example, a query for "all the 
employees in department 10 whose salary is null" can be very efficient for an index on depart- 
ment and salary. 

The null_attribute in an index descriptor defines how an index handles null values. The 
null_at tribute has three options: 



none 



Indicates an index does not allow null values. 
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index_null Indicates an index allows null values, and the filing service enters them in 
the index stnicture. 

no_index_null Indicates the index allows null values, but the filing service does not enter 
them in the index structure. 

Composite keys have the following rules concerning nulls: 

1. Some fields can be null and others may have values. If one field is null, the entire key is 
not treated as null. 

2. Multiple null values are allowed in a unique index. 

3. If you use the no_index_null option in an index and any field in the key is null, the 
entry is not stored in the index. 



NOTE 

Organization indexes do not allow null values. 

In your record layout, you need to account for any variable length fields or fields that 
accept nuU values because the format of a nuU field is different. If a null field is fixed, it 
is preceded by a one byte null indicator. If a nuU field is variable and it is null, the length 
is set to a special constant value. 



IV-8.2 Techniques 



This section presents the techniques for using structured files and indexes. After reading this 
section, you will be able to: 

• Define a record DDef 

• Define an index key DDef for a file 

• Create a file 

• Build an organization index 

• Build an alternate index. 

Chapter IV-3 describes the techniques for copying, emptying, and destroying files. The ex- 
ample package Employee_Filing_Ex in Appendix X-A complete code for the examples 
in this section. 

IV-8.2.1 Defining Record DDefs 

Before creating a structured file, you need to lay out the record structure for your file. The 
most convenient way to do this is to create a record DDef. 
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Calls Used: 

Data_Def inition_Mgt . Create_DDef 

Creates a DDef object to contain the record and fields layout for a record. 

Data_Def inition_Mgt . Create_node 

Creates a record DDef node inside the DDef object 

Data_Def inition_Mgt . Create_simple_f ield 

Creates a field DDef node as a component of a record DDef node. 

Data_Def inition_Mgt .Add_property_value 
Adds a DDef property to a DDef node. 



For example, to create a four-field layout, you must create five nodes and add the properties 
indicated below: 

record DDef node: pi_node_name is Employee_Data, 
pi_meta_type is mt_record, 
pi_root is public_root_node, 
** Field nodes ** 

Dept: pi_node_name is Dept, 

pi_root is non_root_node, 

pi_type is ord_2. 
Name: pi_node_name is Name, 

pi_root is non_root_node , 

pi_type is string, (System_Def s . text) 

pi_header_for_max_length is true, 

pi_varying is true, 

pi_length is 25; 
Job_Desc: pi_node_name is Job_Descr, 

pi_root is non_root_node, 

pi_type is string, 

pi_length is 200; 
Salary: pi_node_name is Salary, 

pi_root is non_root_node, 

pi_type is real8, 

pi_default_value is 0; 

The root DDef node is specified as equivalent to an Ada record structure (that is, it has a record 
metatype). It is declared 2& public so that nodes in other DDef objects can reference it This is 
useful when deriving an index key DDef from this record DDef. 

Each of the field DDef nodes is declared as a non-root node and has various properties such as 
data type, length, and upper/lower bounds added to it For a complete list of these possible 
properties, including supported data types, see the Data_Def inition_Mgt package. 

The DDef structure shown above is equivalent to the following Ada record declaration: 

subtype Job_Desc_length_t is 
integer range . . 200; 

type Employee_Data { 

Job_Desc_length: Job_Desc_length_t) is 
record 

Dept: System. short_ordinal 

range 100 . . 999; 
Name: System_Defs.text (25) ; 
Job_Desc: string (1 .. Job_Desc_length) ; 
Salary: float; 
end record; 
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Be aware that the data definition service determines the alignment rules for each data type. 
Basically, these rules conform to the alignment rules for Ada with the exceptions noted in the 
Data_Def init ion_Mgt package. It's important that you understand these exceptions be- 
fore you define your record layout. 

IV-8.2.2 Defining Index Key DDefs 

The easiest way to create an index key DDef is to derive it fi^om the record DDef. 

Calls Used: 

Data_Def initio n_Mgt . Create_DDef 

Creates a DDef object to contain the definition of an index key DDef. 

Data_Def inition_Mgt . Create_node 

Creates an index key DDef node inside the containing index DDef object. 

Da t a_D ef initio n_Mgt . Create_f ield 

Creates a field DDef node as a component of an index DDef node. This 
field becomes part of the key definition. The field DDef node can simply 
reference the definition of a field in an existing record DDef. 

Data_Def inition_Mgt . Add_property_value 

Adds a DDef property (for example, a reference to a field definition in an 
existing record DDef) to an index key DDef node. 



You derive the index key DDef from the file's existing record DDef. To derive a key using the 
record DDef EmploYee_Data described previously, you set up the following structure: 

record DDef node: pi_meta_type is mt_record, 

pi_root is public_root_node, 
pi_DDef_name is "Employee_DDef ", 

"Employee_Data" , 
pi_derive_all is false, 
** Index key field nodes ** 
Dept: pi_maps_to is "Dept", 

Salary: pi_maps_to is "Salary", 

pi_descending is true. 

This composite index key is set up by mapping DDef nodes fi-om Employee_Data to a new 
record DDef consisting of these fields: 

• Dept in ascending order (defaulted). 

• Salary in descending order. 

The root DDef node is specified as being derived from the structure for the "Employee_Data" 
record layout. It's declared as public so that nodes in other DDef objects can reference it. 
Each of the field DDef nodes is declared as referencing an existing field node. All properties 
associated with each field node in the file's record layout are mapped to the respective field 
node in the index key DDef. 



IV-8.2.3 Creating Files 



When creating a named file, you supply a pathname for the file and its logical file descriptor. 
The logical file descriptor contains options for selecting record formats, record DDefs, trans- 
action locking, and logging. 
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Calls Used: 

File_Admin . Create_f ile 

Creates a permanent file. 

File_Adinin . Create_unnamed_f ile 

Creates a temporary file that exists for the duration of the current job. 



You specify a file using a logical file descriptor. The logical file descriptor contains options 
for selecting record formats, record DDefs, transaction locking, and logging. The 
File_Admin . logical_f ile_descr_record record represents a logical file descrip- 
tor. You must specify a logical file descriptor as parameter to the File_Admin . 
Create_f ile and File_Admin . Create_unnamed_f ile calls to create files. The 
following Create_f ile call creates an unordered file. 

508 new_file := File_Admin.Create_file ( 

509 name => file_name, 

510 logical_f ile_descr => ( 

511 — Set the file's logical 

512 — file descriptor. 

513 file_org => File_Defs .unordered, 

514 DDef_specified => true, 

515 terin_char => File_Defs .term_char, 

516 record_DDef => employee_DDef , 

517 record_layout => ( 

518 DDef_specified => true) , 

519 lock_escalation_count => 0, 

520 xm_locking => true, 

521 — Required for any record locking, 

522 — including transaction locking. 

523 short_term_logging => true, 

524 — Required for transaction support. 

525 long_term_logging => false, 

526 max_rec_num => 

527 max_employee_count, 

528 bytes_per_bucket => 4096, 

529 fill_factor => 

530 File_Admin. fill_factor_dont_care, 

531 org_index => org_index_naine ) ) ; 

To specify the file organization you use the f ile_org field in the logical file descriptor. 
Line 529 specifies the f ile_org parameter as File_Def s . unordered. 

You specify a file's volume layout with a physical file descriptor. There is only one physical 
file descriptor for each data area of a file. The filing service provides a default physical file 
descriptor, so you only need to specify a physical file descriptor when you want to change the 
default (see the File_Admin package). You can specify a physical file descriptor as 
parameter to the File_Admin . 

Create_f ile and File_Admin . Create_unnamed_f ile calls when creating files. 
The File_Admin . Get_physical_f ile_descr caU retrieves a physical file descriptor. 
The physical file descriptor fields you specify optionally include: 

• A description of the number of bytes and volume locations of data areas 

• Initial values for the expansion volume and expansion sizes of data areas. 
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IV-8.2.4 Building Organization Indexes 

You can create indexes for any file organization. Before opening a file for indexed access, you 
must first create the file's organization index. 

Calls Required: 

File_Admin . Build_index 

Builds an index. 



You build an organization index by specifying the correct index descriptor to the 
Build_index call. You specify an index descriptor for each index a structured file has. An 
index descriptor specifies the index's name, the index's organization, and special options that 
indicate (among other options) whether an index can use duplicates, null values, and phantom 
protection. The data structure File_Def s . index_descr_record represents an index 
descriptor. You specify an index descriptor as parameter to the 
File_Admin . Build_index call to build an index. The 
File_Adinin . Get_logical__index_descr caU retrieves an index descriptor. 

The following Build_index call builds an organization index for a unordered file. 

534 File_Admin.Build_index( 

535 file => new_file, 

536 logical_index_descr => { 

537 — Set the index descriptor for Department. 

538 name => dept_index_name , 

539 active => true, 
54 index_org => 

541 File_Defs.btree_index, 

542 duplicates_allowed => false, 

543 duplicate_order => 

544 File_Defs.by_increasing_record_ID, 

545 null__attribute => File_Defs.none, 
54 6 DDef => dept_index_DDef , 

547 phantom_protected => false, 

548 utilization_maintenance => true, 
54 9 bytes_per_bucket => 

550 File_Defs.page_size) ) ; 

Line 538 sets the index name to dept_index_name. Line 540 sets the index organization 
to File_Def s . btree_index. For a hashed file, you set this field to 
File_Def s . hashed_index. Line 546 sets the DDef field to dept_index_DDef , the 
index DDef created earlier. A file's organization index is always active. This assures that the 
organization index structure is always up-to-date so that it may be used to determine the place- 
ment of a newly inserted record. 

The File_Adinin package provides additional calls for getting information about index 
descriptors. These calls are: 

File_Admin .Get_index_names 

Gets the index names associated with the specified file. 

File_Adinin .Get_index_status 

Gets dynamic information associated with the specified index. 
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IV-8.2.5 Building Alternate Indexes 

You can add alternate indexes to any structured file organization. An alternate index (like an 
organization index) requires you to specify an index key DDef as part of the index descriptor 
parameter. 

Calls Required: 

File_Admin . Build_index 

Builds an index. 



You build an alternate index on a previously created file. You specify an index descriptor 
using File_Def s . index_descr_record. You provide the index descriptor as a 
parameter to File_Admin . Build_index. The following example defines a department- 
salary index that uses a composite key built on department and name fields. 

553 File_Admin.Build_index( 

554 file => new_file, 

555 logical_index_descr => ( 

55 6 name => 

557 dept_salary_index_name, 

558 active => true, 
55 9 index_org => 

560 File_Defs .btree_index, 

561 — A unordered org index with 

562 — a b-tree index. 

563 duplicates_allowed => false, 

564 duplicate_order => 

565 File_Def s .by_increasing_record_ID, 

566 null_attribute => 

567 File_Defs.none, 

568 DDef => 

569 dept_salary_index_DDef , 

570 phantom_protected => true, 

571 — Uses bucket-level locking. 

572 utilization_maintenance => true, 

573 bytes_per_bucket => 

574 File_Defs.page_size) ) ; 

Line 556 sets the index name to dept_salary_index_name. Line 559 sets the index 
organization to File_Def s . btree_index, which is necessary for a unordered file. Line 
568 sets the DDef field is set to dept_salary_index_DDef , the index DDef created 
earlier. 

This index is a composite index. Composite keys are sorted field by field in prefix order. The 
greater-than comparison of descending fields is reversed so that their key entries are stored in 
reverse order in the index structure. 

The File_Admin package provides additional caUs for destroying, deactivating, and reor- 
ganizing alternate indexes. These calls are: 

File_Adinin . Destroy_index 

Destroys an alternate index. 

File_Adinin . Deactivate_index 

Deactivates an alternate index. 

File_Adinin . Reorganize_index 

Reorganizes an alternate index. 
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IV-8-3 Summary 

• Use the File_Admin package to manage structured files. 

• DDefs define a file's record and index layout. 

• Define a single or composite index key value using a DDef. You can derive the index key 
DDef fi'om a file's record DDef. 

• You build indexes using the index descriptor record in the File_Def s package. 

• You can build alternate indexes for any structured file organization. 

• Only clustered and hashed file organizations can have organization indexes. 

• B-tree alternate indexes provide fast indexed-sequential and moderate indexed-random ac- 
cess. 

• B-tree organization indexes used as organization indexes for clustered files are best for 
index sequential access. 

• Hashed organization indexes used as organization indexes for hashed files provide very fast 
indexed-random access. 
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This chapter presents the concepts and techniques for using record I/O with structured files. 

Packages Used: 

Record_AM Provides device-independent record I/O. 



Record I/O lets you access records one record at a time from any system device that supports 
record access. This chapter emphasizes using record I/O with structured files. You can use 
these same techniques to access records on other system devices. 



IV-9.1 Concepts 



This section discusses the concepts and terminology related to using record I/O with structured 
files. 

IV-9.1.1 Current Record Pointer 

The current record pointer (CRP) represents the current record location in a file. Figure 
IV-9-1 shows the current record pointer during a read of a sequential file. 
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Figure IV-9-1. A Record I/O Read Operation 



You use the CRP to access records by physical or indexed location. During physical access, 
the CRP points to the current record. You can use the CRP to step through a file's records in 
either forward or reverse sequence. You can set the position of the CRP to the first or last 
record in a file, a record ID, or to a record number. During indexed access, the CRP points to 
the current index value. You can set the CRP to the first, last, or any particular key value. 

You can use the position modifier parameter modifier in record I/O calls to adjust the CRP. 
This parameter can be: 



current 
next 



The current record. 

The next record in the sequence of records. 
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pr io r The prior record in the sequence of records. 

rest_of_current 

The rest of the current record. For reading the unread part of the current 
record when a Device_Def s . length_error is raised during a read 
caU. 

These calls modify the CRP: 

Record_AM.Ops .Delete 

Record_AM . Ops . Read 

Record_AM.Ops .Set_posit±on 

Record_AM . Ops . Update. 

Record_AM . Keyed_Ops . Read_key_value 

These calls do not modify the CRP: 

Record_AM.Keyed_Ops .Read_by_key 
Record_AM . Keyed_Ops . Update_by_key 
Record_AM . Keyed_Ops . Delete_by_key 

Unsuccessful record I/O calls have no effect on the CRP. 



IV-9.1.2 Access Modes 

An access mode determines the order in which records in a file are accessed. You can access 
records either sequentially or randomly, and in either a physical or an indexed order. Depend- 
ing on the operations you perform on a file, some access modes are more efficient. You can 
access structured files with one or more of these access modes: 

physical-sequential Access to a set of records by their physical order. 
physical-random Access to a single record by the record's physical address. 
indexed-sequential Access to a set of records using an index key value range. 
indexed-random Access to a single record using an index key value. 

Sequential operations are always relative to the CRP. Random operations generally do not 
depend on the positioning of the CRP. 

IV-9.1.2.1 Physical-Sequential Access 

You can access any structured file using physical-sequential access. This mode is the fastest 
way to do full file scans. Figure IV-9-2 shows physical-sequential access. 
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Figure IV-9-2. Physical-Sequential Access 



For physical-sequential access mode, you can do the following: 

• Read records in sequence and, based on the record's value, delete or update the current 
record. 

• You read records according to the way the filing service places them physically in the file. 
This is the default mode. 

• Set the CRF's initial position with one or more of these calls: Recor d_AM . Open, 
Record_AM . Ops . Read, or Record_AM . Ops . Set_position. After setting the in- 
itial position, you can read records in sequence using the position modifier. 

• Do not use index ranges. 



NOTE 

Physical-sequential reads on xmordered, clustered, and hashed files read records as they 
are physically located in the file. 

After finishing a read operation, the CRP stiU points to the current record. The CRP 
moves just before the next read. 



IV-9.1.2.2 Physical-Random Access 



In physical-random access, you must precede each Read, Update, or Delete call with a 
Set_position caU to set the position of the CRP. Figure IV-9-3 shows physical-random 
access. 
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Figure IV-9-3. Physical-Random Access 



For physical-random access mode, you can do the following: 

• Read records in sequence and, based on the record's value, delete or update the current 
record. 

• Use the Set_position call to move the CRP to the first position, last position, a record 
ID, or record number (if in a relative file) in a file, 

• Read, update, or delete the current record using the current position modifier. You 
cannot do insertions by record ID or record number. The record ID and record number 
cannot change during the lifetime of a record unless the file is reorganized. 



IV-9.I.2.3 Indexed-Sequential Access 



In the indexed-sequential access mode, you select a range of key values to read. The key range 
determines the subset of records in a file and the logical ordering within the subset. Figure 
IV-9-4 shows indexed-sequential access. 



Using Record I/O with Structured Files 



IV-9-5 



PREUlVnNARY 



Index 




Step(T) Set_key_range 



Current 

Record 

Pointer 



Buffer 





1 J V. 


F77J- 


step (2) Read 


*"7 1 

L|17 


1-3 





Position 
After 
Read 



Figure IV-9-4. Indexed-Sequential Access 
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For indexed-sequential access, you can do the following: 

• Select a range of key values to read. 

• Read records in forward or reverse index order. 

• Use this access mode for any file that has a clustered index or b-tree alternate index or- 
ganization. 

In keyed access, the CRP is actually an index key value. The CRP is initialized by a 
Set_key_range call. You specify an index name and a key value range. You can then 
read, update, or delete records within that range as foUows: 

1. You call Set_key_range to set starting and ending boundaries within the index. The 
values of the starting and ending boundaries depend on whether you are reading an ascend- 
ing or descending index.. 

2. The modifiers next and prior are relative to the index structure, not the key values. For 
example: 

• Reading an index consisting of one descending field wiU return the next lower key value 
using next as a modifier. 

• Reading an index consisting of one ascending field will return the next higher key value 
using next as a modifier. 
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3. The first Read call after a Set_key_range call is relative to the starting boundary 
(which may or may not be inclusive). 

• If the starting boimdary is designated as inclusive and the key value exists, the position 
modifier is ignored. 

• If the starting boundary is exclusive, or the key value specified does not exist, the posi- 
tion modifier is applied to locate a starting position. 

• The position modifier is always applied on subsequent reads. Other aspects of the 
position modifier are the same as those for physical-sequential access. 

4. A Read call returns the actual record defined by the CRP and position modifier. For keyed 
access, it is possible to just read the key values and record IDs of the records. This is done 
by calling Read_key_value. 

• This permits a fast scan via an index without accessing the primary data area. 

• The returned record IDs can be used to read the actual records later, if desired. 

5. Inserts do not affect the CRP (except for relative files where a S etjpos it ion can 
precede an Insert call). The filing service determines the locations of the insertions. 



IV-9.1.2.4 Indexed-Random Access 



In this access mode, records are read randomly by supplying a key value to a unique index. 
Figure IV-9-5 shows indexed-random access. 
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Figure IV-9-5. Indexed-Random Access 



In the indexed-random access mode, you can do the following: 

• Randomly access records without modifying the CRP with the Read_bY_key, 
Update_by_key, and Delete_by_key caUs. 

• Specify a imique index name and an index key value for a particular record. The filing 
service determines the locations of the insertions. 
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IV-9.1.3 Record I/O and Structured Files 

Some structured file organizations only aUow you to use particular record I/O calls. These 
access characteristics apply to the following file organizations. 

IV-9.1.3.1 Sequential Files 

In this file organization, the physical sequence of the records corresponds to the order in which 
they were written. Sequential files have the following access considerations: 

• You establish a current record position using Recor d_AM . Ops . Set_j>os it ion. 

• You can use the ne xt or pr io r position modifiers to position the CRP. A 
Record_AM . Ops . Read call with the modifier parameter set to next returns records 
in the same order as the records are writtea A Record_AM. Ops. Read call with 
modifier set to prior returns records in reverse order. 

• A Record_AM . Ops . Insert call appends a new record at the end of the sequential file. 

• When you read a record with the Record_AM . Ops . Read caU or set the record position 
with the Record_AM. Ops . Set_position call, the Record_AM. Ops . Update call 
overwrites the record at which the CRP points. 

• The length of variable-sized records carmot be changed. 

• The Record_AM . Ops . Delete call is not allowed. 

• The Recor d_AM . Ops . New_lines call inserts a control record with the specified num- 
ber of empty lines in it. 

• The Recor d_AM . Ops . New_page call inserts a control record with a page mark. 

Sequential files with variable-sized records can store control data having no direct relationship 
to the contents of the records. For example, some control data in a file controls the format and 
page layout in text files. This additional information is stored in separate control records 
containing a number of empty lines or page mark characters. The 

Record_AM . Ops . Insert_control_record call inserts a record with control infor- 
mation. You must use the Record_AM . Ops . Set_open_mode caU to set 
Record_AM . read_ctl_rec to true to get control records in read operations, otherwise 
control records are ignored. No index entries are added for control records. 

IV-9.1.3.2 Relative Files 

Relative files have the following access considerations for physical-sequential access: 

• After using Record_AM . Ops . Set_position to initially set the CRP, you use the 
position modifiers next or prior for positioning the CRP. 

• A sequential Record_AM . Ops . Read call returns records in ascending or descending 
order of the record numbers. Empty slots are skipped automatically. 

• A Record_AM . Ops . Update caU overwrites the record you just read. The length of 
variable-sized records may shrink or grow unless it exceeds the maximum record length 
given by the slot size. 

• The Record_AM . Ops . Delete call deletes the record that was accessed by the im- 
mediately preceding Record_AM . Ops . Read call or the record that was defined by the 
preceding Recor d_AM . Ops . Set_position call. 
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Relative files have the following considerations for physical-random access: 

• Access by record number, to the beginning of the file or the end of the file is done by 
calling Record_AM . Ops . Set_position. You do this prior to making 
Record_AM . Ops . Update, Record_AM . Ops . Delete, or 

Record_AM . Ops . Insert calls. 

• For the Record_AM . Ops . Insert call, the filing service inserts the new record in the 
first empty slot if you specify first with Record_AM . Ops . Set_position. If you 
specify last, the filing service inserts the new record at the end of the file. 

• The filing service raises the invalid_r ecord_addres s exception when an addressed 
slot is not empty. 



• 



You can insert records using any record number. For example, if the first record written to 
the file is record number 100, the slots with numbers 1 to 99 are marked empty. 



IV-9.1.3.3 Hashed Files 

Hashed files have the following access considerations: 

• You can do indexed-sequential access only with hashed files having a hashed organization 
index supporting duplicates. 

• Physical positioning is allowed. 

• A Device_Def s . end_of _f ile exception is raised after all duplicates of the current 
key value are read. 

IV-9.1.4Endof File 

The EOF pointer points past the last record in the file to the end-of-file. When end-of-file is 
reached during a read, the Device_Def s . end_of_f ile exception is raised. The 
at_EOF boolean in the operation_status_record data structure also indicates the 
end-of-file. 

The EOF pointer for a storage file may change as records are inserted, updated, and deleted. 
The at_EOF boolean in the operation status record is set when the last record in the file is 
read. A Device_Def s . end_of _f ile exception is raised if a Read is attempted at or 
beyond the current end-of-file. If writers are active in the file, the end-of-file can change in the 
instant after a Record_AM . Ops . Read call. 

IV-9.1.4.1 End of File for Indexed Access 

During indexed-sequential access, the Device_Def s . end_of_f ile exception is raised if 
an attempt is made to read outside of certain boundaries. This attempt is detected in a manner 
consistent in all cases. The cases are: 

• Reading by ascending key values in a descending index structure using prior, starting at 
the lower key value 

• Reading by ascending key values in an ascending index structure using next, starting at 
the lower key value 

• Reading by descending key values in a descending index structure using next, starting at 
the higher key value 

• Reading by descending key values in an ascending index structure using prior, starting at 
the higher key value. 
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Figure IV-9-6 shows how EOF is detected for each of these cases. 
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Figure IV-9-6. EOF Detection During Indexed-Sequential Access 

When reading sequentially via a nonunique index, the system returns the next record of the 
duplicate sequence and sets a duplicate boolean to true if records exist with the same index 
key value. See the operation_status_record in the Record_AM package. 

Reading all duplicates for a single key value can be done for both b-tree and hashed indexes. 
(This is a sequential and not a random operation.) You must use Set_key_range to set the 
start and stop boundaries to the same value. 

When rereading a record using a current position modifier, key_value_changed is 
raised if the key value that was used to locate the record changed as the result of an intervening 
Update or Delete call. 

For a single opened file, you can alternate back and forth between physical-sequential and 
indexed-sequential access by varying the use of Record_AM . Ops . Set_key_range and 
Record_AM.Ops.Set_position calls. 
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IV-9.1.5 Record I/O and Transactions 

Certain record I/O operations will block if a record or file is locked by another transaction. 
The duration of the blocking can be set using a timeout parameter. The default value for 
this parameter is wait_f orever. 

Once an opened file becomes part of a transaction (this is an implicit association), it may not 
be used by another transaction until the first transaction commits or aborts; otherwise 
ODO_using_dif f erent_transaction is raised. (An opened file associates with a 
transaction the first time it is used in a call that reads or modifies records.) 

You can find information on transaction semantics and locking for record I/O calls on files in 
Chapter IV-10. 

IV-9.1.6 Files and Disk Flushes 

In order for a file to be consistent, all information changed by Record_AM . Ops . Insert, 
Record_AM . Ops . Update, or Record_AM . Ops . Delete calls must be physically writ- 
ten to the file. This information includes both your data and any affected system-maintained 
control information. In the case of files, both data buffers and control information are main- 
tained in nonvolatile memory to protea against power failures. Because of this protection, 
information is not flushed from nonvolatile memory to a disk when a file is closed. However, 
a Record_AM . Ops . Flush call is available to write the modified contents of a file to disk at 
anytime. 

IV-9.1.7 Record I/O Operation Status 

The status of a record I/O operation is returned in the operation_status_record. You 
can retrieve operation status after most Record_AM calls. Table IV-9-1 shows information 
available in the operation status_record: 



Table IV-9-1. Operation Status Record 



Parameter 


Description 


rec_length 


Actual record length in bytes if the last call was a "Read". 


rec_ID 


Record ID of the record that was processed by the last successful call. 


rec_num 


Number of the record that was prcKessed by the last successful call. This is 
valid only for relative files. 


insert_dupl 


True if the record has a duplicate in at least one active index that allows 
duplicates, else false. 


at_EOF 


True if an end of file excq>tion is raised, else false. 


at_EOP 


True if the CRP points to the end of a page in a stream file or in a sequential 
file, else false. 


ctl_record 


Trae if the last record read or positioned to was a control record, else false. 


duplicate 

1 


Trae if additional records with the same key value have not yet been accessed 
by a Read or Read key value call, else false. 



Query a file's open status with Record_AM . Ops . Get_open_status. See the 
Record_AM. open_status_record record in the Record_AM package. 
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IV-9.2 Techniques 

After reading this section, you will be able to: 

• Open and close a structured file 

• Set a file's open mode 

• Get record IDs and record numbers 

• Insert a record 

• Read and update a record 

• Access fields in a record buffer 

• Set a key range and read key values sequentially 

• Delete indexed records sequentially 

• Read records using physical-random, physical-sequential, indexed-random and indexed- 
sequential access. 

This section assumes that you are familiar with the record buffering, record DDef, and index 
DDef techniques described in Chapter IV-2. The following techniques cover the common 
cases for using record I/O with different access modes. Appendix X-A provides the complete 
listing for these examples. 

IV-9.2.1 Opening and Closing Structured Files 

Opening a file makes an existing file available for processing. 

Calls Used: 

Record_AM . Open_by_name 

Opens a file using the pathname of the file. 

Record_AM . Ops . Open 

Opens a file using an AD to the file object. 

Record_AM. Ops . Close 

Qoses a file using an AD to the file object. 

The Record_AM package has two open calls. Record_AM . Open_by_name lets you open 
a file by name; Record_AM . Ops . Open lets you open a file with a file AD. An open caU 
returns an opened file that you can use in subsequent file processing operations. If multiple 
processes are allowed access to a file, the filing service maintains a file status for an opened 
file for each particular opening of the file. The open calls let you specify how you want to use 
the opened file and how you want to allow other callers to use the file. You can specify the 
parameters: 

• input_output that specifies the type of I/O you want to do with the file 

• allow that specifies the operations other users can do with the file 

• block that specifies whether to wait for the file if it is in use. 

When you open a file: 
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• You acquire a file-level lock (except when the allow parameter is set to anything). 

• If the file is already opened or locked in a mode which is incompatible with your allow 
mode and you set the block parameter to false, the filing service raises the 
Device_Def s . device_in_use exception. 

• If you set the block parameter to true, you wait until other users release their locks or 
imtil the system interrupts. This terminates file processing and closes the associated 
opened file. 

A Close call terminates access to an opened file. If the opened file was passed to other jobs, 
each job must terminate or close the file before it is totally deallocated. 

IV-9.2.2 Setting Open Mode 

The Set_open_mode call sets particular options that modify the behavior of an opened file. 

Calls Used: 

Record_AM . Ops . Set_open_mode 

Sets boolean values associated with an opened file. 



Possible values are specified using the open_mode_value data structure as foUows: 

read_ct l_rec If true you want to read data records and control records in a sequential or 
stream file; otherwise you want to retrieve only data records. 

load If true a clustered, hashed, or unordered file is opened for initial loading. 

aut o_c lo se If true the current transaction automatically closes the file when it commits 
or aborts; otherwise the file remains open until you close it or your job 
terminates. 

level_3 If true you want level 3 consistency. Chapter IV-10 discusses level 3 

consistency. 

For example, the following procedure sets the open mode level_3 boolean to true: 

72 level_3_mode: Record_AM.open_mode_value (Record_AM.level_3) := 

73 (mode_id => Record_AM.level_3, 

74 value => true) ; 

90 Recor d_AM . Ops . Set_open_mode { 

91 opened_dev => opened_file, 

92 mode_value => level_3_mode) ; 

93 — Sets level 3 consistency. 



IV-9.2.3 Inserting Records 



When you insert a record in a file, the filing service determines where to insert the record in 
the file. Where the filing service inserts the record depends on the file organization. For 
example, the filing service appends a record to the end of a sequential file, but for clustered or 
hashed files it inserts the record based on the file's indexing algorithm. During the insert, the 
filing service automatically assigns each new record a record ID. 
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Calls Used: 

Record_AM . Ops . Insert 

Inserts a record. 



To insert a record into an opened file, you load the record into a record buffer and pass the 
buffer to the Record_AM . Insert call. To load the record into the buffer, you can use an 
Ada address clause or calls in the Field_Access package. 

To use the Ada address clause to load a record buffer, you declare a record buffer and declare 
your record as a virtual address to the buffer. When you assign the record's data to your record 
(for example, an employee record), the record data is located at the address of the record buffer 
which in effect loads the buffer. 

Remember, you need to understand the DDef alignment rules in the 
Data_Def inition_Mgt package if your file references a record DDef. 

IV-9.2.4 Accessing Fields In Record Buffers 

If your file references a record DDef, you can also access a bxiffer using the Fie ld_Ac cess 
package. The Field_Access calls do field alignment and check for null values. 

Calls Used: 

Field_Access . Initialize_record 

Initializes and sizes a buffer for a record based on a DDef and, optionally, 
fills the record's buffer with default values. 

Field_Access . Get 

Gets a value for a single field from a previously initialized record buffer. 

Field_Access .Put 

Puts a value for a single field into a previously initialized record. 



Field_Access aligns the fields according to the record layout definition contained in the 
DDef. It also checks if null values are allowed for a particular field. 

The remainder of the examples in this chapter use an Ada record declaration, rather than the 
field access method. This is possible as long as the representation and alignment of the file's 
record DDef is the same as the Ada declaration (true in most cases, but watch out for varying 
strings since the data definition service lays out the fixed part of the record before the varying 
part). 

IV-9.2.5 Deleting Records 

When you delete a record and its key values, the record is no longer accessible. 
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Calls Used: 

Record_AM . Ops . Delete 

Deletes a record at the position of the CRP. 

Record_AM . Keyed_Ops . Set_key_range 

Sets two key value boundaries within an index. 



To delete a set of records in a key range, you set the key range for the records to be deleted 
with this call: 

379 Recorcl_AM.Keyed_Ops.Set_key_range ( 

380 opened_dev => opened_file, 

381 index => Employee_Filing_EX. 

382 dept_index_name, 

383 select_range => ( 

384 start_comparison => Record_AM. inclusive, 

385 start_value => start_key_descr, 

386 stop_comparison => Record_AM. inclusive, 

387 stop_value => stop_key_descr) ) ; 

The following call reads and deletes the records in the key range: 

388 loop 

389 — CRP is updated after each delete 

390 — (no read is necessary to preface 

391 — the Delete) . 

392 Record_AM.Ops.Delete( 

393 opened_dev => opened_file, 

394 modifier => Record_AM. current, 

395 — Normally defaulted. 

396 timeout => Record_AM.wait_forever, 

397 status => null) ; 
398 

399 end loop; 

When the end of the key range is reached, the filing service raises the 
Device_Def s . end_of_f ile exception which exits the loop. 

In addition to the Record_AM . Ops . Delete call, there is a 

Record_AM . Ops . Truncate call that deletes a specified record and all the records that 

follow it in physical sequence. 

IV-9.2.6 Reading and Updating Records 

You usually update a file by reading a record and doing the update. 

Calls Used: 

Record_AM . Ops . Set_position 
Sets the CRP. 

Record_AM. Ops . Read 

Reads a record from an opened file. 

Record_AM . Ops . Update 

Updates a record. 
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The following example sets a position in the file to begin reading with the 
Record_AM. Set_position call, reads each record into a record buffer, changes the 
record in the buffer, and updates the record in the file. 

578 Record_AM.Ops.Set_position (opened_f ile, 

579 where => Record_AM.record_specif ier ( 

580 type_of_specifier => Record_AM. first) ' ( 

581 type_of_specifier => Record_AM. first) ) ; 

582 loop 

583 bytes_read := Record_AM. Ops. Read ( 

584 opened_dev => opened_file, 

585 buffer_VA => buffer' address, 

586 length => buffer' length) ; 
587 

588 cur rent_record_VA. salary := 

589 pay_raise * current_record_VA. salary; 
590 

591 Record_AM.Ops.Update( 

592 opened_dev => opened_file, 

593 buffer_VA => buffer' address, 

594 length => buffer' length) ; 

595 end loop; 
596 



Each field in the record buffer (for example, a salary field) can be individually addressed by 
specifying the field's name (for example, current_record_VA . salary). 

You can retrieve record IDs and record numbers from the operation status the read calls return. 
You declare a read status variable that contains information about the read, make a 
Set_position call to set the CRP, and read the record. You can then use the status vari- 
able to obtain the record ID: 

42 read_status_VA: Record_AM.operation_status_VA := 

43 new Record_AM.operation_status_record; 

44 — Virtual address of status record. 

67 Record_AM.Ops.Setjposition ( 

68 opened_dev => opened_file, 

69 where => Record_AM.record_specif ier { 

70 type_of_specifier => Record_AM. first) ' ( 

71 type_of_specifier => Record_AM. first) ) ; 

72 loop 

73 bytes_read := Record_AM. Ops .Read { 

74 opened_dev => opened_file, 

75 buffer_VA => buffer' address, 

76 length ~> buffer' length, 

77 status => read_status_VA) ; 

78 if current_record_VA.name = employee then 

79 RETURN read_status_VA.rec_ID; 
80 

81 end if; 

82 end loop; 

You can also use die status variable to obtain the record number: 
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99 Record_AM.Ops .Set_position( 

100 opened_dev => opened_file, 

101 where => Record_AM,record_specif ier ( 

102 type_of_specifier => Record_AM. first) M 

103 type_of_specifier => Record_AM. first) ) 

104 loop 

105 bytes_read := Record_AM. Ops. Read ( 

106 opened_dev => opened_file, 

107 buffer_VA => buffer' address, 

108 length => buffer' length, 

109 status => read_status_VA) ; 

110 if current_record_VA . name = employee then 

111 RETURN read_status_VA.rec_num; 
112 

113 end if; 

114 end loop; 

Note that only records in relative files have record numbers. 

IV-9.2.7 Using Physical-Random Access 

Two cases of physical-random access are discussed here: 

• Reading Records Randomly Using Record IDs 

• Reading Records Randomly Using Record Numbers. 

Calls Used: 

Record_AM.Ops . Set_position 
Sets the CRP. 

Recorci_AM . Ops . Read 

Reads a record from an opened file. 



Reading Records Randomly Using Record IDs. Random reads using record IDs are avail- 
able to all file organizations. You can read records randomly by specifying a record ID: 

151 Record_AM.Ops.Set__position( 

152 opened_file, 

153 where => Record_AM.record_specif ier ( 

154 type_of_specifier => Record_AM. id) ' ( 

155 type_of_specifier => Record_AM. id, 

156 rec_id => rec_ID) ) ; 
157 

158 bytes_read := Record_AM. Ops. Read ( 

159 opened_dev => opened_file, 

160 buffer_VA => buffer' address, 

161 length => buffer' length) ; 

Reading Relative Files Randomly Using Record Numbers. Random reads (using record 
numbers) are available only for relative files. 
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172 begin 

173 Recorci_AM.Ops.Set_position( 

174 opened_file, 

175 where => Record_AM.record_specif ier { 

176 type_of_specifier => Record_AM. number) ' ( 

177 type_of_specifier => Record_AM. number, 

178 rec_num => rec_number) ) ; 

179 bytes_read := Record_AM. Ops. Read ( 

180 opened_dev => opened_file, 

181 buffer_VA => buffer' address, 

182 length => buffer' length) ; 

The records are addressed by a relative record number. The first record is assigned the number 
1, the second the number 2, and so forth. Records can be written by specifying any record 
number (the number does not have to be in a numeric sequence). 

iV-9.2.8 Using Physical-Sequential Access 

There are four basic cases of physical-sequential access: 

• Reading Records in a Forward Sequence Starting at the Beginning 

• Reading Records in a Reverse Sequence Starting at the End 

• Reading Records Sequentially Starting with a Record ID 

• Reading Records Sequentially Starting with a Record Number. 

Calls Used: 

Record_AM.Ops . Set_position 
Sets the CRP. 

Record_AM . Ops . Read 

Reads a record from an opened file. 



You use the same calls and declarations in aU these cases. You set up a record buffer and your 
record as shown on page IV-9-14. Remember that you use the Ada address clause to define 
your record. You can access each field in the record buffer as a virtual address. For example, 
you can specify the salary field with the buffer field name curr ent_record_VA . salary. 

Reading Records Sequentially in a Forward Sequence. This case is used to read all records 
in a sequence starting at the beginning of the file. The current read pointer is positioned to the 
beginning of the file. 

514 Record_AM.Ops.Set__position{ 

515 opened_dev => opened_file, 

516 where => Record_AM.record_specif ier { 

517 type_of_specifier => Record_AM. first) ' ( 

518 type_of_specifier => Record_AM. first) ) ; 

519 loop 

520 bytes_read := Record_AM. Ops. Read ( 

521 opened_dev => opened_file, 

522 buffer_VA => buffer' address, 

523 length => buffer' length) ; 
524 

525 ~ DO ANY NEEDED PROCESSING HERE. 

526 

527 end loop; 
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Each successive record is read in a forward sequence until EOF is detected and 
Device_Def s . end_of_f ile is raised. 

Reading Records Sequentially in a Reverse Sequence. This case is used to read all records 
in a sequence starting at the end of the file. The current read pointer is positioned to the end of 
the file. 

482 Record_AM.Ops.Set_position{ 

483 opened_ciev => opened_file, 

484 where => Record_AM.record_specif ier ( 

485 type_of_specifier => Record_AM. last) ' ( 

486 type_of_specifier => Record_AM. last) ) ; 

487 — Positions current record pointer 

488 — to last record in file. 

489 loop 

4 90 bytes_read := Record_AM. Ops .Read ( 

4 91 opened_dev => opened_file, 

4 92 modifier => Record_AM. prior, 

493 buffer_VA => buffer' address, 

494 length => buffer' length) ; 
495 

4 96 — DO ANY NEEDED PROCESSING HERE. 

497 

4 98 end loop; 

499 

Notice that record_spec is initialized to the last record in the file. The modifier 
value is set to prior. Each successive record is read in reverse sequence until EOF is 
detected and Device_Def s . end_of_f ile is raised. 

Reading Records Sequentially Using Record IDs. Sequential reads using record IDs are 
available to all file organizations. You use the record ID to establish a starting point for a 
sequence of Read calls. Your program must keep track of record IDs using the 
operat ion_status_record in order to specify a record ID from which to start reading. 
You initialize the read to a specific record ID using a rec_ID value fix)m the status infor- 
mation. Use the same techniques as in the example on page IV-9-17. 

Reading Relative Files Sequentially Using Record Numbers. Sequential reads using record 
numbers are available only for relative files. You use the record number to establish a starting 
point for a sequence of Read calls. Your program must keep track of record numbers using 
the operation_status_record in order to specify a record number from which to start 
reading. You initialize the read to a specific record number using a number value from the 
status information. Use the same techniques as in the example on page IV-9-17. 

IV-9.2.9 Using indexed-Random Access 

The only way to manipulate a single specified record using indexed-random mode is to make 
an Update_by_key or Delete_by_key call. These calls do not affect the CRP. 

Calls Used: 

Record_AM. Keyed_Ops . Update_by_key 

Updates a record by key value from an opened file. 



An Update_by_key call requires you to specify Record_AM . key_value_descr 
record which supplies the key value for the update. Otherwise, the record at the current posi- 
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tion of the CRP is updated. In the following example, the record at the current position is 
updated. 

621 current_record_VA. salary := 

622 pay_raise * cur rent_record_VA. salary; 
623 

624 — Default is the current record. 

625 Record_AM.Keyed_Ops .Update_by_key ( 

626 opened_dev => T2_opened_file, 

627 buffer_VA => buffer' address, 

628 length => buffer' length, 

629 index => Employee_Filing_EX. 

630 dept_salary_index_name) ; 

631 — Employee ID index. 

In this example, an employee's salary is raised and the salary is updated. 

IV-9.2.10 Using Indexed-Sequential Access 

Indexed-sequential access lets you read in a forward or reverse sequence in a file using the 
index. 

Calls Used: 

Record_AM. Keyed_Ops . Set_key_range 

Sets two key value boundaries within an index. 

Record_AM . Ops . Read 

Reads a record from an opened file. 



The result of the Read is different depending on whether the index is ascending or descending, 
and whether the key range is being traversed in a forward or reverse sequence. 

Reading in a forward sequence. To read forward in a simple index, use the next option as 
the modifier value to your Read call. 

Follow these steps: 

• Specify an index with an index DDef field that does not have the pi_des cending 
property identifier (that is, the field is sorted in ascending order). 

• Set the start value of the index key range to a minimum value at which you want to begin 
reading. 

The read starts from the low key value and ascends to the high key value in the key range, 
going fi"om left to right in the index structure until Device_Def s . end_of_f ile is raised. 

This example uses a simple single-field index on department (ascending). 
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107 — A simple index declaration. 

108 dept_index_DDef : Data_Def inition_Mgt . 

109 node_reference; 
110 

111 dept_index_name : constant 

112 File_Defs.index_name := 

113 (max_length => File_Def s. index_name_length, 

114 length => 14, 

115 value => "Dept_Index_DDef "); 
116 

117 type dept_key_buffer is 

118 record 

119 dept : department_number; 

120 end record; 

KThis procedure positions to the beginning of the range, and reads successive records until the 
end of the range. You set the start value to the left of the index (the low end), and a stop value 
to the right of the index (the high end). You set the key range to start at the low end of the key 
range and stop at the high end. 

212 Record_AM.Keyed_Ops . Set_key_range ( 

213 opened_dev => opened_file, 

214 index => 

215 Employee_F i 1 ing_EX . dept_index_name , 

216 select_range => { 

217 start_comparison => Record_AM. exclusive, 

218 start_value => start_key_descr, 

219 stop_comparison => Record_AM. inclusive, 

220 stop_value => stop_key_descr) ) ; 

The simple index is read by ascending key values starting at the low end of the key range. 

222 loop 

223 bytes_read := Record_AM. Ops. Read { 

224 opened_dev => opened_file, 

225 modifier => Record_AM.next, 

226 — Next is normally defaulted. 

227 buffer_VA => buffer' address, 

228 length => buffer' length) ; 
229 

230 — DO ANY NEEDED PROCESSING HERE. 

231 

232 end loop; 

Reading in a reverse sequence. To read in reverse in a simple index, use the prior option 
as the modifier value to your Read call. 

FoUow these steps: 

• Specify an index with an index DDef field that does not have the pi_descending 
property identifier (that is, the field is sorted in ascending order). 

• Set the start value of the index key range to a maximum value of the range at which you 
want to begin reading. 

The read starts with the high key value of the key range and reads to the low key value of the 
range, going from right to left in the index structure until Device_Def s . end_of _f ile is 
raised. 

This example uses a simple single-field index on department (descending). 
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107 — A simple index declaration. 

108 dept_index_DDef : Data_Definition_Mgt . 

109 node_reference; 
110 

111 dept_index_name : constant 

112 File_Defs.index_name := 

113 {max_length => File_Defs. index_name_length, 

114 length => 14, 

115 value => "Dept_Index_DDef "); 
116 

117 type dept_key_buf fer is 

118 record 

119 dept: department_number; 

120 end record; 

The start value is set to the right of the index (the high key value of the key range). The stop 
value is to the left of the index (the low key value of the key range). You set the key range 
with the start value (high end) and stop value Gow end) values. 

266 Record_AM.Keyed_Ops.Set_key_range { 

267 opened_dev => opened_file, 

268 index => 

269 Employee_Fi 1 ing_EX . dept_index_name , 

270 select_range => ( 

271 start_comparison => Record_AM. exclusive, 

272 start_value => start_key_descr, 

273 stop_comparison => Record_AM. inclusive, 

274 stop_value => stop_key_descr) ) ; 
275 

The index is read by descending key values starting at the high end of the key range. 

276 loop 

277 bytes_read := Record_AM. Ops. Read ( 

278 opened_dev => opened_file, 

279 modifier => Record_AM. prior, 

280 — Sets read modifier to prior. 

281 buffer_VA => buffer' address, 

282 length => buffer' length) ; 
283 

284 -- DO ANY NEEDED PROCESSING HERE. 

285 

286 end loop; 

IV-9.2.11 Reading Key Values Sequentially 

The Record_AM . Keyed__Ops package provides keyed operations that let you read just the 
key values of records. 

Calls Used: 

Record_AM. Keyed_Ops . Set_key_range 

Sets two key value boundaries within an index. 

Record_AM . Keyed_Ops . Read_key_value 

Reads key values from an opened file. 



Reading key values is no different than reading records. However, the primary data area of the 
file is never touched when key values are read. This allows a fast scan of the values in an 
index without the overhead of reading entire records. 
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To read duplicates of one key value, you must specify a nonunique index and set the start and 
stop values of the index to the same value. 

The following declaration sets the start and stop values to the same value. 

299 start_key_value : constant Employee_Filing_EX. 

300 dept_key_buffer := (dept => 305); 

301 — Start value for duplicate 

302 — key field. 
303 

309 

310 stop_key_value: constant Employee_Filing_EX. 

311 dept_key_buffer := (dept => 305); 

312 — Stop value for duplicate 

313 — key field. 
314 

When reading sequentially via a nonunique index, the next key value is returned in a duplicate 
sequence. The duplicate field in the operat ion_status_record is set to true if 
additional records exist with the same key value. 

IV-9.2.12 Reading and Updating Records by Key 

Sequential reads by key can be combined with random updates. 

Calls Used: 

Record_AM. Ops . Set_key_range 

Sets two key value boundaries within an index. 

Record_AM. Keyed_Ops . Delete_by_key 

Deletes a record designated by a unique index key value. 



Essentially, you do a series of reads until you find a record you need to update: 

542 Record_AM.Ops.Set^osition ( 

54 3 opened_dev => opened_file, 

54 4 where => Record_AM.record_specif ier ( 

545 type_of_specifier => Record_AM. first) ' ( 

546 type_of_specifier => Record_AM. first) ) ; 

547 loop 

54 8 bytes_read := Record_AM. Ops. Read ( 

54 9 opened_dev => opened_file, 

550 buffer_VA => buffer' address, 

551 length => buffer' length) ; 
552 

553 if current_record_VA.dept = 175 then 

554 Record_AM.Keyed_Ops .Delete_by_key { 

555 opened_dev => opened_file, 

55 6 index => Employee_Filing_Ex. 
557 dept_index_name) ; 

558 

559 end if; 

560 

561 end loop; 



IV-9.3 Summary 



• Recor d_AM can be used with a number of different devices including files, DDefs, pipes, 
and directories. 
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Structured files are generally accessed using Record_AM. Only indexed structured files 
can use the Keyed_Ops nested package. 



• The CRP points to the current record. NonnaUy, this is the most recently read record or the 
current index and index key value. The CRP can be physically positioned to a particular 
record using Set_position or Set_key_range calls. 

• Keyed access can also occur without setting the CRP using Read_by_key , 
Update_by_key, and Delete_by_key caUs. 

• Physical-sequential access can be done fi"om the beginning of a file in a forward sequence, 
from the back of a file in a reverse sequence, or by record ID or record number (from any 
random starting point). 

• The major difference between physical-sequential access and physical-random access is 
that each read is preceded with a Set_position call for physical-random access, while 
physical-sequential access uses the next position modifier. 

• Indexed-sequential access depends on the properties of the DDefs used to define the in- 
dexes (that is, ascending or descending). Both ascending and descending indexes can be 
read in either forward or reverse order. 
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The filing service is built for high levels of concurrency and integrity. It uses sophisticated 
algorithms to support readers while writing, provides highly concurrent b-tree and hashed in- 
dexes and supports transaction based synchronization and recovery. For applications that want 
to eliminate the overhead of transactions, the filing service also supports nontransaction- 
oriented files. 



Packages Required: 

Record_AM Provides device-independent I/O for record access. Contains the 

Record_AM . Ops and Record_AM . Keyed_Ops packages. 

Record_AM . Ops Common interface for record I/O calls. 

Record_AM . Keyed_Ops 

Special I/O calls for indexed access to files. 



File Admin 



Basic declarations and calls for file administration. 



In a multiuser system that does not support transaction locking, lost updates can occur. For 
example, when updating a record in a file, you read the record from passive store into a private 
copy, update your copy, and write the copy back to passive store. You can lose your update if 
another user reads the same record you are updating before your write completes, updates their 
copy, and writes their copy back to passive store after your write completes. Figure IV- 10-1 
shows how a lost update can happen. 



Transaction 1 



Transaction 2 
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Figure IV-10-1. Lost Update Problem 



Locking can prevent lost updates. 



IV-10.1 Concepts 



Some problems that can occur in multiuser systems that allow more than one user to access a 
file simultaneously are: 

• . Lost updates - when one user overwrites another user's changes. 

• Reading uncommitted changes - when a user reads data modified by transactions that have 
not completed. 



IV- 10-2 



Locking Flies and Records 



PRELIMINARY 



• Nonreproducible reads - when a user reads the same record twice in a transaction getting 
different results each time. 

These problems can be avoided by using locking features the filing service provides. 

IV-10.1.1 Concurrency Control and Recovery 

An efficient online multiuser data processing system should: 

• Assure that the data accessed by the users looks consistent from their viewpoint, especially 
when multiple users are trying to access the same pieces of data (concurrency control). 

• Assure that any changes to the data are undone if a transaction has an unsuccessful termina- 
tion (rollback). 

• Assure that any changes to the system's data are redone if there is a media failure, system 
crash, or application error (rollforward). 

The filing service supports concurrency control by providing transaction-based locking and 
recovery by using logging techniques. The filing service provides two different logging tech- 
niques: 

• Short-term logging to support rollbacks of transactions 

• Long-term logging to support roUforward operations. 

The filing service lets you use locking, short-term logging, and/or long-term logging for any 
structured file, by appropriately setting the following fields in the logical file descriptor when 
creating the file: 

xm_l o c ki ng Specifies that the file can be locked for transactions. 

short_term_logging 

Specifies short-term logging to support rollback for transaction aborts. 

long_term_logging 

Specifies long-term logging to support rollforward for recovery from 
media failure or user errors. 

Any structured file you create with at least one of the locking or logging fields set to true is 
called a transaction-oriented file. Any file you create with all the locking and logging fields 
set to false is a nontransaction-oriented file. Nontransaction-oriented files do not support 
transaction locking, short-term logging, or long-term logging, and do not have the transaction 
overhead associated with transaction-oriented files. Nontransaction-oriented files are more 
efficient to use in applications where concurrency control and recovery are not important. 

NOTE 

If you do not have a transaction when accessing transaction-oriented files, the filing ser- 
vice wiU automatically start a transaction and commit it at the end of the operation. 

AU the transactions started internally by the filing service are low-overiiead transactions. 
The only exceptions are the long-term logged files where the filing service starts real 
transactions. 
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I V-1 0.1 .2 Transaction Locking 

Most locking is done implicitly by the filing service when you access or modify the data 
contained in files. However, tiie filing service does provide the option to place certain locks 
explicitly, and to drop some locks. 

The filing service uses hierarchical locking for concurrency control. The three levels of the 
hierarchy are: 

• Files (highest level) 

• Index key ranges 

• Records Gowest level). 

Figure IV-10-2 shows the locking hierarchy. 




Records 
Figure IV-10-2. Locking Hierarchy 



A record-level lock locks one individual record. An index-key-range-level lock locks all the 
records whose index key fields fall in the range that is being locked, which is usually a subset 
of the records contained in a file. A file-level lock locks all the records in the file. File-level 
locks are more efficient, because only one lock is required to lock all the records in a file. 
Record-level locks provide better concurrency, because each transaction locks only a subset of 
records in a file. 
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IV-10.1.2.1 Lock Modes 

There are two basic lock modes supported by the filing service: 

• read (r) lock (shared or s-locks). 

• write (w) lock (exclusive or x-locks) 

Read locks prevent other transactions from updating a record. This lock mode allows other 
transactions to read but not modify the record. Write locks prevent other transactions from 
reading or updating the record. Figure IV- 10-3 shows how write locks prevent other users 
from accessing records you are using. 



Transaction 1 



Transaction 2 



_|_ Read and W-locks 
record A 



J_ Tries to read and 
W-lock record A 
(must try again, 
T1 has W-lock on it) 



-h Modifies record A 

Writes record A 
Commit 



Reads and W-locks 
record A (record A 
has Tl's updates) 

Modifies record A 
+ Writes record A 



Figure IV- 10-3. An Update with an X-lock 



In the figure IV- 10-3, transaction 2 cannot read record A until transaction 1 commits, because 
transaction 1 holds a write lock on on it. 

To understand locking, it is necessary to explain several locks that are not visible to trans- 
actions. In addition to the read and write locks, the filing service uses intention locks. Inten- 
tion locks tag an entity at a higher level and indicate that locking is being done at a finer level. 
(Only the read, write, and protect locks are visible to you. The intention-read and intention- 
write locks are used internally by the filing service.) For instance, an intention lock on a file 
indicates that locking is being done at a lower (key range or record) level. There are three 
intention locks: 

• intention-read (ir) lock (also known as intention-share or is-lock) 

• intention- write (iw) lock (also known as intention-exclusive or ix-lock) 
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• protect (r-iw) lock (also known as shared intention-exclusive or six-lock). 

For instance, when there are record-level write locks in a file, the filing service puts an 
intention-write lock at the file-level. This prevents other transactions fix)m placing a file-level 
write lock on the same file. 

The protect (r-iw) lock is a combination of read (r) and intention-write (iw) locks. A protect 
lock is useful for transactions that may want the exclusive right to modify a file, but want to 
allow other transactions to read the file. The protect lock is also useful for transactions that 
may want to read many records but update only a few. 

Another lock mode is the dirty read (null) lock. This lock mode does not provide any locking. 



NOTE 

If you lock one level of the locking hierarchy, the lower levels of the hierarchy are 
considered locked with the same lock mode. For example, when a file is locked with a 
write lock, all the records in that file are considered locked with a write lock. 

IV-10.1.2.2 Lock Mode Compatibility 

Table IV- 10-1 shows the compatibility between lock modes. 

Table IV-10-1. Compatibility of Locks 
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Compatibility between lock modes is an issue only when different transactions are competing 
for the locks on the same record or file. All locks within the same transaction are always 
compatible. 



IV-10.1.3 Acquiring Loclcs 



Transactions implicifly acquire locks when they read or write records in a file. The filing 
service always places write locks on records that are written (inserted, updated, or deleted). 
For reads, the filing service allows you to choose the lock-mode for the record being read. The 
default lock for reading is the read_lock. 

For applications that read records before updating them, you can place a write lock on the 
record when you read it. Therefore, the filing service does not have to upgrade the lock to a 
write lock during the record update. On the other hand, for applications where consistency is 
unimportant, you can do a dirty read using the dirty_read lock mode. With a dirty read, 
transactions do not acquire locks and other transactions can change the data you are reading. 

Transactions can explicitly acquire file-level locks by calling Record_AM . Ops . Lock_all 
and setting the by_transaction parameter to true. With file-level locks, you do not need 
to have locks with the same mode at the key range or record level, avoiding the overhead of 
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individual record locks. Transactions can also acquire file-level locks implicitly through lock 
escalation by the filing system. The appropriate file-level intention locks are always acquired 
whenever a lock is placed on a record or key range. 

See page rV-10-8 for information about how transactions acquire locks from subtransactions. 



IV-10.1.4 Lock Escalation 



The filing service automatically attempts to upgrade the file-level lock, when a transaction 
reaches a threshold for the number of record locks a transaction can hold in the file. (The 
filing service tries to convert the transaction's record locks to a single file-level lock.) The 
filing service raises the lock_escalation_f ailed exception if it is unable to upgrade 
the lock. 

When creating a file, you can specify the lock_escalation_count in the file's logical 
file descriptor to set the threshold value for the file's record locks. If you set this value to zero, 
the exception Record_AM . too_many_locks is raised when a transaction exceeds the 
default limit for the nimiber of record locks per file per transaction. 



IV-10.1.5 Releasing Locks 

The filing service automatically releases all the locks acquired in the transaction when a trans- 
action terminates. However, you can explicitly release some read and protect locks before a 
transaction terminates. 

There are several ways to release read and protect locks. You can release file-level read locks 
and file-level protect locks using the Record_AM . Ops . Unlock_all call. (You need to 
set the by_transaction parameter to true.) You can release record-level read locks using 
the Re c or d_AM. Ops. Unlock call. Only one instance of a lock is released unless the 
unlock parameter is set to all_read_locks. (If a lock has been acquired a number of 
times, each instance of the lock must be unlocked to completely unlock the file or record.) 
You can also release record-level read locks in the Record_AM . Ops . Read or 
Record_AM . Keyed_Ops . Read_key_value calls, by setting the unlock parameter to 
free or all_read_locks. 

IV-10.1.6 Consistency Levels 

A transaction can have different levels of consistency. In general, as the level of consistency 
increases, the amount of concurrency decreases. The filing service provides support for the 
following levels of consistency: 

Level 3 Transactions with level 3 consistency are serializable, that is, their be- 

havior is the same whether they are run concurrently or seridly according 
to some serial order. 

Level 3 transactions guarantee that all modified data is kept locked until 
the end of the respective transactions, repeated reads always give the same 
results, and phantoms are prevented. 

Level 2 Transactions with level 2 consistency guarantee that all modified data is 

kept locked until the end of the respective transactions, and that none of 
the data the transaction reads is dirty (changed but not committed by other 
transactions). No guarantees are made as to whether reads are repeatable 
and whether can phantoms occur. 
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Level 1 Transactions with level 1 consistency only guarantee that the data that is 

modified is kept locked until the end of the respective transactions (dirty 
reads). No other guarantees are made. 

NOTE 

A phantom is a nonexistent entity whose appearance after a transaction has started would 
change the results of the transaction. 

Phantom protection may reduce concurrency and should be switched off unless neces- 
sary. 

With level 3 consistency, the filing service automatically sets key range locks on record fields 
in an index when a transaction accesses a file through the index. When a transaction holds key 
range locks, no other transaction can write (insert, delete, or modify) records in the key range 
(phantom protection). 

Your application has level 3 consistency when: 

• Phantom protection is set. You do this by building indexes with the 
phantomjprotected boolean set to true in the index descriptor. 

• Key range locking for the opened device is turned on. You turn on key range locking with 
the Record_AM . Ops . Set_open_mode call setting the open mode value 
Record_AM . level_3 to true. 

Your application can have level 2 consistency when: 

• Transactions release read locks before they complete. 

• Key range locking for an opened device is turned off. You do this with the 
Record_AM . Ops . Set_open_mode caU setting the open mode value 
Record_AM . level_3 to false. 

Your application can have level 1 consistency when: 

• Transactions do reads without placing any locks (dirty read). A dirty read is set for a read 
caU using a lock mode of Record_AM . dirt y_read. 

lV-10.1.7 Reading Key Range Values 

When an application is interested only in reading key values in an index (by using the call 
Record_AM . Keyed_Ops . Read_key_value) but not the whole records, you can turn 
record locking off. This can be done by setting the no_record_lo eking parameter to 
true. You can do this only if the index is phantom protected and the opened device has level 3 
consistency. 

IV-10.1.8 Locking and Nested Subtransactions 

The filing service supports logically nested subtransactions that are useful for providing 
synchronization in multithreaded applications and for constructing the building blocks for 
transaction-oriented applications. You can use subtransactions to build large applications by 
suitably nesting one building block within another. You can also use subtransactions to devel- 
op applications where the operations in a transaction need to be split into smaller atomic units. 
Splitting a transaction into smaller units provides a convenient way of containing errors, and 
provides a way of building more reliable software in a distributed environment. 
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Transactions and subtransactions can inherit locks from their child transactions. Inherited 
locks behave differently from the other locks described in this chapter. 

When a child transaction commits, the parent subtransaction inherits the locks the child held. 
These inherited locks then become available to other descendants of the same parent. A des- 
cendant can acquire a lock in the base (noninherited) form as long as the lock being acquired 
does not conflict with the locks held by any other transaction. To transactions that are not 
descendants, the inherited locks look and behave similarly to the base locks. 

If the child transaction aborts, the locks disappear and cannot be inherited. 

The inherited locks are called the held locks. There is a held lock mode corresponding to each 
lock mode; for instance, when a write lock is inherited, the inherited version is caUed write- 
held lock. 

Figure IV- 10-3 shows how locks are inherited by subtransactions. In the figure, T2 cannot 
acquire a write lock on file F2 until T8 commits. 

To release a read lock in a subtransaction before the subtransaction has terminated, you can 
specify these values for the unlock parameter in the read caUs: 

unlock_to_held 

The subtransaction releases the (read) lock, and its parent inherits the lock. 

free The subtransaction releases the (read) lock, but the parent does not inherit 

it. 

all_read_locks_to_held 

AU the read locks associated with a particular subtransaction are released. 
The parent inherits the locks. 

all_read_locks 

All the read loclcs associated with a particular subtransaction are released. 
The parent, however, does not inherit the locks. 

If these parameters are specified for a root level transaction, the unlock mode 
unlock_to_held is equivalent to the free mode, and all_read_locks_to_held 
mode is equivalent to the all_read_locks mode. 

You can also release file-level and record-level read locks by calling 
Record_AM. Ops . Unlock_all and Record_AM. Ops . Unlock respectively. 
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Figure IV-10-4. Locks Inherited by Subtransactions 



IV-10.1.9 Lock Contention 



Deadlock is a condition where two or more transactions arc in a simultaneous wait state, each 
waiting for the other transactions to release a lock before it can proceed. The filing service 
uses two independent schemes for avoiding transaction deadlocks. 

The default mechanism for avoiding deadlock is the timestamp ordering mechanism. If two 
transactions contend for the same lock, the filing service uses their timestamps to avoid dead- 
locks. When contending for a lock, a transaction can wait for another transaction that holds the 
lock when the other transaction has an earlier timestamp. If the transaction that wants the lock 
has an earlier timestamp, it is not allowed to wait. Subtransactions are exceptions to this rule: 
a parent transaction can wait for a lock held by a child transaction, even though the parent 
transaction has an eariier timestamp. 
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Instead of the timestamp ordering mechanism, you can use the timeout mechanism to break 
deadlocks. Most Recorci_AM calls have a timeout parameter that specifies the amount of 
time a transaction should wait for a lock. When you specify a timeout value in a call, the filing 
service makes sure that your transaction waits no longer than the duration of the timeout for 
any single lock. The Record_AM . timeout exception is raised at the end of the timeout 
period if the lock is unavailable. 

If you give a timeout value of zero, the Record_AM .timeout exception is raised if a trans- 
action cannot obtain a lock immediately. The timeout value wait_f orever is the default 
value, and switches the transaction into the timestamp ordering mechanism. 

The Transaction_Mgt package allows you to specify timeouts for transactions. A timed 
out transaction raises a TransactionJMgt .transaction_not_active exception. 
You can also break deadlocks using calls in the EventJMgt package to send signals (events) 
to a process that is blocked for a lock. Operations that are interrupted by a signal raise the 
exception System_Def s . system_call_interrupted. 

See Chapter II-4 for more information about transactions. 



I V-1 0.1 .10 Logging 

The jRling service supports short-term and long-term logging of transactions. Short-term log- 
ging provides rollback recovery for transactions. You can request short-term logging when 
you create a file by setting short_term_logging to true. Short-term logging ensures that 
changes made in a file are rolled back if a transaction aborts or the system crashes. 

When a subtransaction commits, the changes are passed on to the parent transaction. The 
changes are made permanent only when the root-level transaction commits. When a subtran- 
saction aborts, the changes made in the subtransaction and the ones inherited from its children 
are roUed back. 

Long-term logging provides rollforward recovery for transactions. You request long-term log- 
ging when creating a file by setting long_term_logging to true. Long term logging can 
be requested only for files that are transaction locking files and are short-term logged. The 
filing service uses the long-term log information to restore a file by rolling forward all the 
changes made to a file since a particular backup. Only the changes that a root-level transaction 
commits are rolled forward. 

lV-10.1.11 Transactions and Opened Device Objects 

Two or more transactions cannot use the same opened device simultaneously. The exception 
Record_AM. odo_using_a_ciif f erent_transaction is raised if a transaction at- 
tempts to open a device that is already opened by another transaction. 

NOTE 

After a transaction releases the lock on the opened device, the value current is invalid 
for the current record pointer (CRP). The CRP has to be redefined in a new transaction. 
The values next and prior are valid. 
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IV-10.1.12 File-Level Locks Associated witii Opened Devices 

In addition to the file-level locks associated with transactions, the filing service associates 
file-level locks with opened devices. These locks apply to both files transaction-oriented and 
nontransaction-oriented, and are independent of transaction locks. 

The filing service automatically associates file-level locks with opened devices when a file is 
opened. The lock mode is based on how you open the file using the input_output and 
allow parameters. Table IV-10-2 shows the lock modes. 

Table rV-10-2. Lock Modes for Opened Device Locking 
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The kind of lock held by an opened device determines the operations allowed by other opened 
devices on a file. For instance, a write-lock disallows any other opens on a file, while a 
read-lock disallows all opens for writing to the file. 

You can explicitiy add and remove file-level locks associated with an opened device, using the 
Record._AM . Ops . Lock_all and Record_AM . Ops . Unlock_all calls. The 
by_transaction parameter must be set to false. You cannot remove the locks that the 
filing service automatically places at the time of doing the open. 

All the locks associated with an opened device are released when the opened device is closed. 
IV-10.1 .13 File Administration Operations and Locking 

The File_Admin package provides calls for managing files and indexes. Some of the file 
administration caUs are transaction-oriented, and they interact with file processing on 
transaction-oriented files. File administration uses the same set of transaction locks to obtain 
isolation as those used by file processing. 

File administration places write locks on files for File_Admin . Create_f ile and 
File_Adinin . Destroy_f ile operations. If a transaction-oriented file is being read, the 
filing service wiU not allow a destroy file operation until the transaction that is reading the file 
has completed. File administration places intention-read locks on the file for the 

Save_unnamed_f ile, Build_index, and Destroy_index operations. 

IV-10.2 Techniques 

When you finish this section you should be able to write transaction-oriented applications that 
support different levels of consistency. 

IV-10.2.1 Using Level 3 Consistency 
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Calls Required: 

Record_AM . Ops . Set_open_mode 

Sets the open mode parameter level_3 to true. 

Record_AM. Keyed_Ops . Set_key_range 

Sets the index key range for the read. 

Record_AM. Ops . Read 

Reads a record from an opened device. 

Record_AM. Keyed_Ops . Update_by_key 

Updates the employee records by key values. 



The following example starts a transaction that performs an indexed-sequential read and up- 
date of a clustered file using a unique b-tree alternate index. The transaction reads employee 
records using the write_lock lock mode, and updates the records with a new salary value. 
The transaction does not release the locks on its records as it reads them; it holds them until it 
resolves. Other transactions are not allowed to read or write the file until the transaction 
commits. 

85 opened_file := Recorcl_AM.Open_by_name ( 

86 name => file_name, 

87 input_output => Device_Def s . inout, 

88 allow => Device_Defs .anything) ; 
89 

90 Record_AM.Ops . Set_open_mode { 

91 opened_dev => opened_file, 

92 mode_value => level_3_mode) ; 

93 — Sets level 3 consistency. 



111 loop 

112 bytes_read := Record_AM. Ops. Read ( 

113 opened_dev => opened_file, 

114 buffer_VA => current_record_addr, 

115 length => Employee_Filing_Ex. 

116 max_rec_size, 

117 lock => Record_AM.write_lock, 

118 unlock => Record_AM.no_unlock) ; 

119 — Another caller cannot read or update 

120 — the same record at any time. 
121 

122 if current_record_VA. salary = 3_000.00 then 

123 curr en t_record_VA. salary := 

124 current_record_VA. salary + 300.00; 
125 

126 Record_AM.Ops.Update( 

127 opened_dev => opened_file, 

128 modifier => Record_AM. current, 

129 buffer_VA => current_record_addr, 

130 length => Employee_Filing_Ex. 

131 max_rec_size, 

132 timeout => Record_AM. wait_forever, 

133 status => null) ; 

134 end if; 

135 end loop; 
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IV-1 0.3 Summary 

• Locking is used to control concurrent access to the records, files, or key range values. 

• There are transaction-oriented files and nontransaction-oriented files. Some files are more 
transaction-oriented than others. 

• Transaction-oriented files can do transaction locking, short-term logging, and/or long-term 
logging. 

• Transaction and opened devices can acquire locks. Transactions can lock files or records; 
opened devices can only lock files. 

• Key range locking provides phantom protection. 

• Locks held by child transactions can be passed to parents. 

• Changes made in a file that uses short-term logging are rolled back if a transaction aborts. 

• The long-term logging information is used to restore a file by roUing forward all the 
changes made to a file since a particular backup. 

• A lock held by an opened device determines what kinds of opened devices and activities 
are allowed on a file. 

• Nontransaction-oriented files do not support transaction locking, short-term logging, or 
long-term logging. 
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This chapter describes the filing service's support for processing collections of records. 

Packages Used: 

Join_Interface 

Provides support for performing nested block joins of records from mul- 
tiple opened devices. Only authorized users can use the calls in this pack- 
age. 

Re CO r d_AM Provides device-independent I/O for records. 

Record_Processing_Support 

Provides support for processing large collections of records. 

Sort_Merge_Interface 

Provides calls for sorting and merging records from one or more input 
devices into a single ordered record stream. 

Trusted_Record_Processing_Support 

Provides additional support for processing collections of records. Only 
authorized users can use the calls in this package. 



The record processing packages provide special calls for developing large record processing 
applications such as database filing systems. Figure IV- 1 1-1 shows how you can customize a 
read call to do special processing of records in a file: 
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Figure IV-11-1. Customizing a Read Call 
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The Trusted_Record_Processing_Support . Associate_read_procedure as- 
sociates an implementation for a read call with an opened device. When you read from the 
opened device, the filing service wiU use your implementation for the read call. 



IV-11.1 Concepts 



The operations for processing collections of records are more efficient than the record I/O 
techniques in Chapter IV-9 because: 

• They minimize the processing time and the data transfer necessary between system file 
buffers and the user's address space. 

• They can reduce the associated disk activity (seeks and latency). 

• They minimize, in the distributed applications, the amoimt of commimication necessary 
between nodes. 

• They are efficient for processing collections of records. 



IV-11.1.1 Reading Records 



The calls in the record processing support packages let you read record fields and read data 
fiom a single index. You can use these calls together with the Record_AM read calls to 
create applications that efficiently read collections of records. You can use the record process- 
ing support calls together with these Re cor d_AM read calls: 

• Record_AM . Ops . Read - reads a record from an opened device 

• Record_AM . Keyed_Ops . Read_by_key - reads a record from an opened device 
given a unique key value 

• Record_AM . Keyed_Ops . Read_key_value - reads a key value form an opened 
device. 

These record processing caUs are for reading collections of records: 

• Record_Processing_Support . Set_oriented_read - for reading all the 
records on a device 

• Trusted_Record_Processing_Support . Associate_read_procedure - for 
customizing your read procedures. 

The Set_oriented_read call lets you read a complete file with one call instead of having 
to write a call that does this. This is convenient when you want to read all the records on a 
device. 

The Associate_read_procedure call lets you customize a read call with your own 
implementation of the call. To use the Associate_read_procedure call, you provide 
an implementation for the 

Trusted_Record_Processing_Support . Process_record (a subprogram 
template for a read procedure), and pass its subprogram type as the read_f unction 
parameter to Associate_read_procedure. Once you associate your read implemen- 
tation with an opened device, the read call will use your implementation to read records from 
the opened device. Because this call is in the Trust ed_Record_Proces sing_Support 
package, you must be an authorized user to use it. 
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NOTE 



During a Set_oriented_read call, you can buffer the output records to one or two 
output streams. During the Associate_readjprocedure call, returns a single 
buffer when the buffer is fuU and ready to be written. 



IV-11.1.1.1 Record Streams 



In record processing, you read collections of records called record streams. A record stream 
device is an opened device that is either: 

• A sequential file that does not contain any indexes or use any transaction locking 

• A pipe that is a stream of records. 

You use record stream devices as temporary devices to hold the output from the record 
processing operations. 

If you store record IDs in a record stream device, you create a record ID stream. A record ID 
stream is a record stream in which each record contains a record ID. Most of the record 
processing support calls use record ID streams to process records. 

You can use the Associate_record_ID_stream call in the 
Record_Processing_Support package to associate a record ID stream with a file. 
Figure IV- 11-2 shows an operation using record IDs and a file's primary data. 
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Figure IV-Il-2. Associating a Record ID Stream with a File 



You can direct a record stream or record ID stream to an output device using the Record_AM 
read caUs or the Set oriented read caU. 
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IV-11.1.1.2 DDefs and Record Processing Support 

You can use data definitions (DDefs) to define the fields used for processing records. You can 
derive your DDef fix)m the record DDefs of the file that is the specified input device for your 
application. See Appendix X-A for examples of derived DDefs. 



IV-11.1.2 Updating Records 

Using the basic record I/O calls, you update a record by reading and updating the entire record. 
But this is often inefficient when updating collections of records, because you usually only 
update a single field in each record rather than the entire record. 

To efficiently update collections of records, you can use the Record_AM update calls together 
with the record processing support calls. You use these Record_AM calls for updates: 

• Record_AM . Ops . Update - updates a record or record fields on an opened device 

• Record_AM . Keyed_Ops . Update_by_key - given a unique key value, updates a 
record on an opened device. 

Using the Record_Processing_Support . Associate_update_f ields call, you 
can associate any number of fields to update with an opened device. Only the record fields 
you specify are updated. You can specify any number of fields to update with 
f ields_to_update parameter. When you make an update call and specify a record, the 
filing service examines your buffer to find the new values for those fields. The filing service 
then logs the changes to the record and maintains any indexes that are affected by the update. 

Variable-length fields may change in length when they are updated, and multiple value fields 
may have values added or deleted. The filing service automatically expands and contracts 
variable-length records to accommodate this. 

IV-11.1.3 Database Operations 

By combining the record processing calls and the Record_AM calls, you can implement many 
database and filing operations. The filing service provides special record processing support 
for these database operations: 

• selection - extracts specific records (rows) from a given device. 

• projection- extracts specific fields (columns) from a given device. 

• intersect- builds a relation consisting of only the records appearing in two or more 
streams. 

• difference - builds a relation consisting of all the records appearing in one stream, but 
not in any other given streams. 

• union - builds a relation consisting of aU records appearing in all of the given streams. 

• join- combines the given streams by concatenating all of the records in the streams, 
creating a stream with all the combinations of records in the given streams. 

Figure IV- 11 -3 shows the database management operations. 
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Figure IV-11-3. DBMS Operations 



Selection lets you select individual records or a collections of records from one or more opened 
devices. The read calls in the Record_AM paclcage provide the basic caUs needed to perfonn 
record selection. For example, you can use tiie Record_AM . Keyed_0ps call 
Set_key_range to set the range of key values to read in a file, and the Recor d_AM . Ops 
caU Read to read aU the employee records in a given department. You can do this without 
reading the records for the employees in any other departments. See Chapter IV-9 for ex- 
amples of how to do this. 
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The Record_Processing_Support package provides this call to optimize record selec- 
tion: 

• Associate_record_ID_stream - for associating a record ID stream with an opened 
device with read rights. 

The Associate_record_ID_stream call helps you select records by their record IDs. 
This call associates a record ID stream with the opened device you want to read. When you 
call Set_oriented_read, the record IDs of the records you are reading are automatically 
output to the associated record ID stream. 

IV-11.1.4.1 Customizing a Selection 

You can use the caUs in the Trusted_Record_Processing_Support package to cus- 
tomize the implementation of your selection operatioa This package provides two caUs for 
optimizing record selection: 

• Associate_index_selection_f unction - for customizing your own index selec- 
tion function. 

• As sociate_r ead_jprocedur e - for customizing your own read caU for record selec- 
tion. 

These caUs let you associate a selection implementation with an opened device. Whenever a 
read caU is made to that opened device, the filing service uses the associated read implemen- 
tation for the device to do the read. You can only use these calls if you are an authorized user. 

IV-11.1.4.2 Using the Associate_index_selection_function Call 

To use the Associate_index_selection_f unction call, you must provide the 
opened device the selection function is associated with and a subprogram type for the selection 
function. (See the System package for a description of the BiiN™ Ada 
System . subprogram_type type.) The selection function must be an implementation of 
the Trust ed_Record_Processing_Support .Entry_qualif ies call that does 
record selection with an index. You pass the subprogram type for your implementation of this 
call in the Associate index selection function call's selection function 
parameter. You can do this with the BiiN Ada subprogram_type attribute. When you 
execute a read on the associated device, the read will automatically use your 
Entry_qualif ies implementation to perform the read. 

IV-11.1.4.3 Using the Associate_read_procedure Call 

To use the Associate_read_procedure call, you provide an implementation for the 
Trusted_Record_Processing_Support . Process_record that does record selec- 
tion, and you associate your implementation with the opened device you are reading from. 
Your call returns the selected part of the record when records are read fix)m the device. 

You can also use Associate_read_procedure to do record projection or both record 
selection and projection in a single procedure. 



IV-1 1.1 .5 Projection 



Projection is a database operation that extracts record fields (columns) from an opened device. 
This is most efficient for processing fields in records, rather than entire records. For example, 
the projection operation could get certain employee ID numbers in an employee database by 
accessing only the record fields with the ID numbers instead of the entire employee record. 
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You can set up projection operations for reading or updating fields in an opened device using 
eitiier primary or index projections. You can use tiiese Record_Processing_Support 
calls for projection operations: 

• Associate^rimary_data_pro jection - associates a projection of the primary 
fields with an opened device. 

• Associate_index_pro jection - associates a projection of the index fields with an 
opened device. 

To create a projection operation, you must first associate a projection with an opened device. 
Figure IV- 1 1-4 shows a record projection operation that reads only the requested fields in an 
indexed file. 



Fields 

in 

Record 




File 



AssociQte_primary_data_pro jection 



Read 



Fields 
in Buffer 











B 




C 









Associates a 
projection with 
an opened device 
for fields B and C. 



For each record 

in read set, 

returns only fields 

B and C to the 

caller's buffer. 



Figure IV-Il-4. A Primary Data Projection 



The projection operation is created using the Record_Proces sing_Support . 
As sociate_jprimary_data_pro jection call to associate the projection operation 
with a read caU for an opened device. After setting up a projection, any read caU on the 
opened device automatically projects to the output stream the fields in each record you specify 
in your projection implementation. 

IV-11.1.5.1 Using the As sociate_primary_data_pro jection Call 

The As sociate_primary_data_pro jection lets you specify the primary data fields 
you want to project, and whether you want the output with record IDs. You specify your 
output with these parameters: 



The fields to be extracted from the primary data of the record being 
read. 



primary_fields 

record_ID_output The record ID of the record being read is included in the output 
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If you specify both parameters, the output appears in this order: 

[record ID, primary fields] 

This call creates a projection of an opened device's primary data area. Each time a read call 
reads a record from the opened device, the primary fields are projected to the output device 
associated with the read call. The projection writes the primary fields in the order you specify, 
with fixed length fields first followed by the variable length fields. 

IV-11.1.5.2 Using the As sociate_index_j>r ejection Call 

To project only key values, you can use the As sociat e_index_pr o j ect ion call. You 
specify your output with these parameters: 

key_value_output The specified key to be extracted from the index data of the file being 

read. If this key does not exist, the read produces erroneous results. 

record_lD_output The record ID of the record being read is included in the output. 

When you specify both parameters, the output appears in this order: 

[record ID, key value] 

With this caU, you can only access the secondary data area containing the index's key values 
during a read. The rest of the record is inaccessible. For each record, a record ID and/or the 
key value is returned to the output device. Prior to making this call, you must set the index key 
range with a caU to Record_AM . Keyed_Ops . Set_key_range. 

You can also use Trusted_Record_Processing_Support call 
As sociat e_read_j3rocedure to create your own projection operation. 

I V-1 1 .1 .6 Difference, Intersection, and Union 

Three calls in the Record_Processing_Support package manipulate streams of 
record_IDs to provide low-level support for the database operations intersection, union, and 
difference. 

• Intersect_record_IDs - forms the intersection of two record ID streams. 

• Union_record_IDs - forms the imion of two record ID streams. 

• Dif f erence_record_IDs - forms the difference of two record ID streams. 

These calls let you perform intersection, union, or difference on the record ID streams created 
by a selection or projection operation. 

IV-11.1.7 Interaction Between Record Processing Calls 

Certain combinations of the record processing caUs are incompatible when you use them on 
the same opened device. A record processing call disables an incompatible call that is active 
on the same device. Table IV- 1 1-1 lists the record processing calls and the calls they are 
incompatible with. 
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Table IV-11-1. Interaction of DBMS Calls 



Call 


Disables these calls 


Associate_read_piocedure 


Associate_piimaiy_data_projection 
Associate mdex_projection 


Associate_primaiy datajprojection 


Associate_read_procedure 
Associate_mdex_pK)jection 


Associate_index_projection 


Associate_read_pnx:edure 
Associatelprimary datajpiojectitm 


AssocUte_index_selection_/imction 


Associate_record_ID_stream 


Associate_reconiJD_stream 


Record_AM.Set_key_range 
Associate_index_sd[ection_functioa 


Record_AM.Set_position 


Reconi_AM.Set key.nmge 

Associate_recorJ_II)_stream 

AssociateIindex_seiection_function 


Record_AM.Set_key_range 


Associate_record_ID_stream 
Associate_index_selection_funcUon 



IV-11.1.8Joins 



The join operation lets you join together records from multiple opened devices into one opened 
device based on the values of common fields. Figure IV- 1 1-5 shows a join using two input 
files. 
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Figure IV-11-5. A Join Operation 



The Join_Interf ace package provides two calls: 

• Join - the call that joins the records from the input devices producing a single stream of 
joined records and an optional stream of alternate records. 

• Bloc k_ join- the function template you provide for joining blocks of records. 
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The Join call performs the low-level block access to data in the input devices, and in the 
process calls your implementation of the Block_Join call that actually performs the join. 

When you make a call to Join_Interf ace . Join, you specify a list of input devices in the 
participatin g_de vi c e s parameter. If you only specify one input device, you only 
access the primary data in the input device. You reserve the buffers for the join with the 
buffers_to_re serve parameter. You specify the record streams for the output in the 
join_output and alternate_output parameters. The user_info parameter returns 
the process-specific information for the join procedure. 

The parameter join_jprocedure specifies an implementation of the Block_join func- 
tion. This parameter is the subprogram type of your implementation of the join operation. 
You obtain the subprogram type value by applying the BiiN™ Ada subprogram_type at- 
tribute to the block join implementation you want to use. 

Join calls your implementation of Block_ j oin. Your implementation of this call: 

• Joins the sets of records 

• Fills the output buffers 

• Requests the next set of input from the Jo in call. 

The Block_ join operation gets the set of records you want to join from the records 
parameter. This parameter is the list of record locations for each input device, and contains 
null ADs the first time Block_ join is called. Block_ join completes the join and fills the 
output buffers. Block_ join then returns a cominunication_block_VA type that con- 
tains the next block list, the output buffers, and a request for the next set of records. You must 
instantiate the coramunication_block_VA data structure prior to the Block_ join caU. 
You can pass this data structure into Block_ join as part of the user_inf o parameter. If 
there are more blocks to join, the process is repeated. 

The join operation only provides data from files; any selections associated with files cannot be 
active during a join. To select records for a join, you must do a selection on the file to produce 
a record ID stream, and pass the record ID stream to the Join call. 

I V-1 1 .1 .9 Sorting and Merging 

You use sorting and merging to produce one ordered record stream from one or more record 
streams. Figure IV- 1 1-6 shows how records can be sorted and merged. 
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Figure IV-11-6. Sorting and Merging Records 



The Sort_Merge_Interf ace package provides these calls for sorting and merging record 
streams: 

• Sort - sorts a single record stream and produces an ordered stream of records. 

• S ort_merge - sorts and merges an arbitrary number of input record streams, and 
produces a single ordered stream of records. 

• Special_collation_sort_merge - sorts and merges records with arbitrary string 
fields ordered by a collating sequence that you specify. 

You can only use Sort_Merge_Inter f ace calls to sort opened stractured files or pipes. 
If you attempt to sort records using an unsupported device, the sort/merge service does not 
return exceptions. You cannot use Sort_Merge_Inter f ace calls with transactions. If 
you try to use these calls with transactions, the operations wiU not be atomic and exceptions 
will not be raised. 



IV-11.1.9.1 Sorting Records 



To sort records, you specify the input device (where you are reading the records from) and the 
output device (where you want to write the records to). Because the sort calls use the 
Record_AM . Ops caUs Read and Close to access input devices, you must assure that the 
input device is opened to allow physical-sequential or indexed-sequential reading of records. 
The reads begin at the current position of the input device and continue until 
Device_Def s . end_of _f ile is raised. After the sort, the input and output devices 
remain open. 

The Sort call sorts records from a single opened input device. The Sort_Merge and the 
Special_collat ion_sort_merge calls can sort and merge records from one or more 
input devices. The Sort_Merge and Special_collation_sort_merge calls take the 
parameter input_devices, a variable-length an-ay of input descriptors. Each descriptor 
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specifies an opened input device (file or pipe) and a boolean indicating whether or not the 
records are presorted. 

You select the level of concurrency you want for an input device. An opened input device can 
be opened for exclusive use (no concurrency) or shared use (dirty read). Generally, you should 
pass in an exclusively opened device (no concurrency). 

You can also specify tuning options with the tuning_opts parameter. These options in- 
clude options for gathering statistics, for indicating the volume set to use for work files, and for 
indicating specific woik files to be used during the sort. 

Any read options or record processing operations associated with an input device are passed 
along with the device. 



IV-11.1.9.2 Sort Ordering 



The sort ordering is normally based on values of a sort/merge key composed of typed fields 
that you must lay out using a DDef (see Chapter IV-8 for a description of how to create 
DDefs). You must assign each field of the DDef in the sort/merge key a pi_descending 
value of either true (descending) or false (ascending). The default value is false. 

The ordering of multiple input devices in the input_devices parameter can determine the 
ordering of records with duplicate key values when those records appear on different input 
devices. (Options for ordering records with duplicate key values, by insertion time or by 
record ID, only hold within a single file.) For example, you specify three input devices in the 
order A, B, and C. Device A has a record a; device B has the records bl and b2; device C has 
record c. All these records have identical key values. The ordering of the input devices 
determines the output, which can be either a/bl/b2/c or a/b2/bl/c. (If B was presorted 
or you specify stable_sort, the relative ordering of bl and b2 are the same in the output 
as the input. Otherwise, their ordering is arbitrary.) 

The Special_collation_sort_merge caU takes the additional parameter 
alternate_CS for specifying an alternate collating sequence for string fields. (See the 
string collating sequences required by the runtime systems of certain languages such as 
COBOL.) The ordering of each string field is normally performed using tiie ASCII collating 
sequence. You must specify any alternate collating sequence. A collating sequence is an array 
of 256 b)^s where CS ( x ) = N implies that a byte with a value x should be ordered as if it 
held the value N in the standard numeric ordering. A collating sequence can map more than 
one byte value to the same ordering value, that is, CS { x ) = N = CS ( y ) is allowed. 



IV-11.1.9.3 Stable Sorts 



You can optionally specify a stable sort with the stable_sort parameter. A stable sort 
preserves the original ordering of records with duplicate key values within a file. This kind of 
sort is typically inefficient than an unstable sort. 

The sort operations also support unique sorts, which are sorts that delete duplicates from the 
final output. 



iV-1 1.2 Techniques 

After reading this section, you will be able to: 
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• Select a set of records 

• Set up a projection using an index 

• Join records fh)m two different opened devices 

• Sort records fix)m a single file 

• Sort and merge records from two files. 

The examples used in the following sections are in the example packages called DBMS_Ex and 
Join_Ex. See Appendix A for complete listings. 

IV-1 1.2.1 Selecting a Set of Records 

To select records in a file you either use a Read call or a Set_or iented__read call. 

Calls Used: 

Record_Processing_Support . Set_oriented_read 

Sequentially reads an opened file and sends all data to an output device 
until end-of-file or a user interrupt. 



Typically, you associate a read implementation with the device you you want to do the selec- 
tion from, and then do the read, lie read implementation you supply actually does the selec- 
tion. This example uses the Set_oriented_read caU to automatically read a file sequen- 
tially xmtil the end-of-file. After reading the records, they are written to the output devices you 
specify instead of being copied into a buffer. This allows two output streams to be created 
from a single pass of the input file (for example, the selected records and the rejected records). 
This is more efficient for applications in which the records read from a file are destined to be 
immediately rewritten to another device. 

The Set_oriented_read call takes two locking parameters: 

lock Specifies the lock mode of every record read. 

unlock Specifies the unlock mode of every record read. 

These parameters are ignored if the file being read is not transaction-oriented. 

The unlock parameter is the same as the one specified in Record_AM . Ops . Read. 
Records can be incrementally imlocked as the set of records is read (each previous locked 
record is unlocked in the specified mode). 

The timeout parameter is also the same as the one specified in Recor d_AM . ops . Read. 
The timeout is the maximum time to block waiting for a single record lock. 
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57 Trusted_Record_Processing_Support . Associate_read_proceclure ( 

58 opened_dev => opened_file, 

59 user_info => System. null_address, 

60 read_procedure => read_procedure) ; 
61 

62 

63 Record_AM . Keyed_Ops . Set_key_range ( 

64 opened_dev => opened_file, 

65 index => 

66 Employee_Filing_Ex. dept_index_name, 

67 select_range => ( 

68 start_comparison => Record_AM. inclusive, 

69 start_value => start_k;ey_descr, 

70 stop_coinparison => Record_AM. inclusive, 

71 stop_value => stop_key_descr) ) ; 
72 

73 Record_Processing_Support . Set_oriented_read ( 

74 opened_dev => opened_file, 

75 modifier => Record_AM.next, 

76 output_device => Process_Globals_Support_Ex. 

77 Get_standard_output, 

78 — Normally defaulted. 

79 alt_output => System. null_word, 

80 no_record_lock => false, 

81 lock => Record_AM.read_lock, 

82 unlock => Record_AM.no_unlock, 

83 timeout => Record AM. wait forever); 



IV-11.2.2 Using Projection on an Index 

You can project the values for selected fields in records during a read. 

Calls Used: 

Record_AM. Keyed_Ops . Set_key_range 

Sets two boundaries within an index. 

Record_Processing_Support .Associate_index_projection 

Sets up a projection of the values for specified key fields in a composite 
index during a read. 

Record_AM . Ops . Read 

Reads only the previously specified field values in each record that is read. 
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134 — Filters out all fields except those specified 

135 — in the DDef. 

136 Record_Processing_Support . 

137 Associate_j5rimary_data_pro jection < 

138 opened_dev => opened_file, 

139 record_ID_output => false, 

140 primary_fields => projection_DDef_ref ) ; 
141 

142 

143 loop 

144 — Only reads the fields specified in 
14 5 — the DDef. 

14 6 bytes_read := Recor d_AM. Ops. Read ( 

147 opened_dev => opened_file, 

148 modifier => Recor d_7^. next, 
14 9 — Normally defaulted. 

150 buffer_VA => current_record_addr, 

151 length => System. ordinal ( 

152 Employee_Filing_Ex.max_rec_size) ) ; 
153 

154 — DO ANY NEEDED PROCESSING HERE. 

155 

156 end loop; 



IV-11.2.3 Joining Records from Two Devices 

You join records from two (or more) different opened devices in blocks. The system does the 
join of the devices (files); you supply the join semantics. 

Calls Used: 

Join_Interface .Block_join 

Provides a template for a user-supplied function that joins blocks of 
records in memory buffers. 

Join Interface. Join 



289 Join_Interf ace. Join < 

290 participating_devices => join_devices, 

291 buffers_to_reserve => buf fer_reservation, 

292 user_info => u_info' address, 

293 join_procedure => 

294 Join_ex' subprogram_value, 

295 join_output => out_file, 

296 alternate output => System. null word) ; 



IV-11.2.4 Sorting Records in a Fiie 

You can easily sort records from a single opened input device to an opened output device. 

Calls Used: 

Sort_Merge_Interf ace . Sort 

Sorts the records from a single input device to produce an ordered stream 
of records. 
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You specify the opened input device (from which the records are to be sequentially read) and 
the opened device (to which the sorted records are to be sequentially written). You must 
assure that the input device is opened in a manner that allows physical-sequential reading of 
records and provides for the desired level of concurrent use of the device. Physical-sequential 
reads begin at the current position of the input device and continue until 
Device_Def s . end_of _f ile is raised. After the sort, the input and output devices are 
automatically closed. 

193 Sort_Merge_Interf ace . Sort { 

194 input_cievice => inventory_file, 

195 DDef => invent ory_DDef_ref, 

196 output_device => Process_Globals_Support_Ex. 

197 Get_standard_output , 

198 stable_sort => true, 

199 tuning_opts => Sort_Merge_Interface . 

200 no_tuning) ; 

You have the option to specify whether the sort is stable, that is the original ordering of 
records with duplicate key values within a file is preserved. A stable sort is typically in- 
efficient than a corresponding unstable sort. You also have tuning options; these include 
options for gathering statistics, for indicating the volume set to use for work files, and for 
indicating specific work files to be used during the sort 

IV-1 1.2.5 Sorting and Merging Records from Two Files 

In addition to sorting records from a single opened input device, you can also sort and merge 
records from an arbitrary number of sorted or unsorted input devices. 

Calls Used: 

Sort_Merge_Interf ace . Sort_merge 

Sorts the records from a single input device to produce an ordered stream 
of records. 



Sort_merge takes the same parameters as Sort. In addition, it takes the parameter 
input_devices, which is a variable-length array of sort-merge input descriptors. Each 
descriptor specifies an opened input device that supports Record_AM . Ops . Read and a 
boolean indicating whether or not the records are presorted. The ordering of multiple input 
devices in this array determines the ordering of records with duplicate key values when those 
records appear on different input devices. (Options for ordering records with duplicate key 
values ~ by insertion time or by record ID - only hold within a single file.) 

248 — Perform the sort -merge. 

24 9 Sort_Merge_Interf ace . Sort_merge ( 

250 input_devices => sort_input_array, 

251 DDef => sort_DDef_ref, 

252 output_device => Process_Globals_Support_EX. 

253 Get_standard_output, 

254 stable_sort => true, 

255 tuning_opts => Sort_Merge_Interface. 

256 no_tuning) ; 
257 
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IV-1 1.3 Summary 



• 



• 



• 



• 



Use record processing support for large applications for which you want to perfonn opera- 
tions on only selected data in files. 

Record processing support operations are associated with opened devices. Selected field 
values (in a file's primary data area), record IDs, and/or index key values can be supplied 
with each individual record during reads. Selected field values can be updated. 

DDefs are used to define the field values used by filters. These DDefs should be derived 
from the record DDef used to define a file's record layout 

A record stream device can be a non-transaction-locking sequential file (without indexes) 
or a record-oriented pipe that consists of record IDs. Record stream devices can be as- 
sociated with an opened device for a file so that records (or records fields) in the file are 
selected on the basis of the record IDs in the record stream device. 

Record streams can be used to perfomi the relational database operations difference, union, 
and intersection. 

You can write your custom read and custom index selection routines to associate with open 
devices. However, this is not possible for most users. 



• You can write your own block join routine to bring together information contained in mul- 
tiple files into a single file based on the values of common fields. Your custom procedure 
gets record location information contained in currentiy processed blocks of data. This, also, 
is not available to most users. 
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PartV 

Human Interface Services 



TM 

This part of the BUN I OS Guide discusses services used for interacting with users. 

Understanding Human Interface Services 

Basic concepts of Human Interface Services. 

Creating a BiiN™ Application 

An example of a simple, complete application program which uses Human 
Interface Services. 

Building New Commands 

Reading and processing program-defined invocation and runtime com- 
mands. 

Programming with Command Language Variables 

Reading, creating, and setting job and session variables. 

Programming with Menus 

Displaying menus and processing menu selections. 

Understanding Forms 

Describes data entry/display forms and the form service. 

Programming with Forms 

Displaying and processing forms for data entry and display. 

Programming with Reports 

Setting up and printing reports from data records. 

Human Interface Services contains the following services and packages: 

Command Service 

CL_Defs 

Command_Execut ion 
Command_Handler 
Environment_Mgt 
He lp_Text_Adm 

Form Service 

Form_Defs 
Form_Handler 

Report Service 

Report Handler 
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This chapter provides a general overview of the BiiN™ system's user interface software. 

The next eight chapters discuss how to create a BiiN™ program, including interacting with the 
user: using commands, variables, menus, and forms for input, and variables, forms and reports ' 
for output. 

Figure V-1-1 shows the relationships between the five Human Interface Services and an ap- 
plication program. 




Figure V-1-1. Human Interface Services and a BiiN™ Program 



• Read Chapter V-2, "Creating a BiiN Application", to understand the relationships be- 
tween an application program and various service areas, including Human Interface Ser- 
vices. 

• Read Chapter V-3, "Building New Commands", to use the command service to create and 
use program-specific commands. The BiiN^ Command and Message Guide describes how 
to create command definitions interactively. 

• Read Chapter V-4, "Programming with Command Language Variables", to use the 
environment service to read and write CLEX user, and job variables. 
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• Read Chapter V-5, "Programming with Menus", to use the menu service to create menus 
and read menu selections. 

• Read Chapter V-5.3, "Understanding Forms", for the concepts necessary to use the ^rm 
service for user input and data display. 

• Read Chapter V-7, "Programming with Forms", to use forms, change a form's appearance 
and structure, and get data from and put data into forms. 

• Read Chapter V-8, "Programming with Reports", to use the report service to write reports 
from data records. 

• Read Chapter TBD, "Interacting with Users in Standard Ways", for guidelines on how to 
use Human Interface Services in a maimer consistent with the BiiN™ system's own 
programs and utilities. 

Chapter II-5 describes how to create and display messages, including help messages. The 
manage .messages utility creates and maintains files of messages; it is described in the 
BUN™ Command and Message Guide. 

Human Interface Services is composed of five service areas: 

Command Service Manages the command interface. Also manages command language (job 
and session environment) variables. 



CL Defs 



Contains declarations used by the command service, 
for processing command language (CL) arguments and 
variables. 



Form Service 



Report Service 



Command_Execution 

Contains a procedural interface to command execution. 

Command._Hand.ler 

Contains operations for reading and processing 
program commands and arguments. 

Environment_Mgt 

Contains operations to get, set, or remove local and 
global environment variables. 

He lp_Text_Adm Manages command and form help texts. 

Manages fornis, for structured data input and display. 

Form_Def s Defines types and constants used by the Form_ 

Handler package. 

Form_Handler Provides calls to process, control, and change forms. 

Generates reports; formats data records for display. 

Report_Handler 

Provides calls for initializing and printing a report. 



V-1.1 Concepts 



Human Interface Services provide methods of interacting with human users. The model is that 
a user controls an appUcation program to create, retrieve, update, and display information. 

To control a program, a user has a choice of commands or menus: 
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commands Provide a set of free-fomi commands, each with appropriate arguments and 

default values. The command service provides calls to prompt the user to 
enter a command, returning the command's index and name, and its ar- 
gument values. 

memis Provide a list of choices. The menu service provides calls to enable the 

user to make a menu selection, then to read the selection indexes. 

The environment service provides calls to read command language variables, including job 
variables in active memory, and user and system variables in passive store. Variables can be 
created and set in active memory. 

The form service provides calls to display a data entry form, prompting the user to enter a 
complete, consistent data record. 

The report service provides a caU to initialize a report, given its definition and input and output 
devices. Another call prints the initialized report. 

Some Human Interface Services are based on data definitions, or DDefs. There are DDefs for 
commands, menus, forms, and reports. The term definition, as in a command definition, is 
used throughout this chapter to refer to the underlying DDef . For more information on DDefs 
and specific DDef properties, see the Data Definition Mgt and 
DDF_Ut i 1 it y_Suppor t packages in the BUN I OS Reference Manual. 

Once a file's record definition (DDef) has been created, it can be used to automatically 
generate a default data entry form and a default report. 

V-1 .1 .1 Why Use Human Interface Services? 

TM 

These services provide consistent, standard methods of interacting with the user. A BiiN 
user, on invoking your program, is already familiar with the user interface. 

The BiiN™ OS, and the system utilities, caU these services to interact with the user. 

The primary value of Human Interface Services is that each service performs its own process- 
ing, returning a complete result to your program's request. 

Extensive "help" is provided by the services. You define the help texts, and attach each text to 
the appropriate point (a program, a command, a menu item, or a form's field). The help text is 
displayed upon the user's "help" request. 

For example, after your program displays a form, the user can move through the data fields, 
request form-specific help, and be prompted to correct invalid or inconsistent entries, aU with- 
out your program's intervention. When the user completes the form, valid input data is then 
available. 

V-1 .1.2 Utilities 

Several utilities are used with Human Interface Services, to set up variable groups, and to 
create command, menu, form, and report definitions. 

Figure V-1-2 shows the relationship between a service's utility, the definition it produces, and 
the service your program calls. 



V-1 -4 Understanding Human Interface Services 



PRELIMINARY 




Figure V-1-2. Utility, Data Definition, and Service 



Command Service Utility 



manage . commands 

Creates both invocation command and command set 
definitions, defining all commands and their ar- 
guments. See the BiiN^ Command and Message 
Guide for more information about using the 
manage . commands utility to create command 
definitions. 

manage . variable_group 

Manipulates groups of variables, creating, modifying, 
and storing variable groups. The environment service 
then reads and writes these variables; the environment 
service does not provide calls to create group vari- 
ables. 



Form Service Utilities 



create . standard_f orm 

Creates a default form definition, given a file's record 
definition. The default definition can then be used 
with the form service, or revised using the 
edit . form utility. 

edit . form Creates and modifies form definitions, including all 

fields and values. See the BUN™ Systems Form Editor 
Guide for more infonnation on defining fonns. 
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edit . key_map Edits a fonn's keyboard mapping. This becomes part 
of a form's definition. 

Report Service Utilities 

create . standard_report 

Creates a default report definition from a file's record 
definition. The default definition can then be used 
with the report service, or revised using the 
edit . report utility. 

edit . report Creates and modifies report definitions, including all 
fields, column headings, and control breaks. See the 
BiiN^ Systems Reports Guide for more information on 
defining reports. 

Help texts are defiaied within each service's utilities. Messages are defined with the 
manage .messages utility, or with the manage .messages command set in the 
manage . program utility. See the BiiN^ Command and Message Guide for more infor- 
mation on defining help texts and messages. 



V-1,1.3 Command Service 



The command service is used to parse and execute commands entered to your program. CLEX 
uses this interface for its own commands. 

Figure V-1-3 shows the relationship of a BiiN™ program to the command service. 
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Program 
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Figure V-1-3. BiiN™ Application Program and the Command Service 
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V-1.1.3.1 Command Concepts 



• 



New commands are defined using the manage . command command set in the 
manage . program utility - see the BiiN^ Command and Message Guide. 

The command service uses the command definitions - to help the user correctly enter and 
complete a command. 

There are three types of commands - processed by the command service: built-in 
commands^ CLEK commands, dcm^ program-defined commands. 

built-in commands Part of, and processed by, the command service itself. Built-in runtime 
commands directly perform some action, such as setting a variable 
(set . variable). Built-in control commands control the logical 
flow of commands (if / then / else / endif). 

CLEX commands Commands specific to the command language executive (CLEX). 

program-defined commands 

Each program has an invocation command, which is entered to CLEX 
to invoke (execute) the program. Programs using the command service 
define their own runtime commands, which control and are im- 
plemented by the program. 

A command consists of up to three parts: 

conunand.name [ :argument=value] . . . 

[ : :control_option=value] . . . 

command . name The name of the command. 

•.argument = value 

Zero, one, or more arguments may be part of a command. 

- Arguments have a name, a type, and a value - an argument name is 
a string of characters, preceded by a colon (**:", for example, 

: argument_name). The argument type is one of seven: boolean, 
integer, range, string, string list, pointer, or "derived". A derived 
argument's actual value may be any of the other types. The ar- 
gument value's type must match the defined argument type. 

- Arguments may be mandatory or optional - mandatory arguments 
must be entered with the conmiand name. Optional arguments may 
be entered to specify an argument value other than the default value, 
if any, defined with the command. 

: :control_option = value 

There are several control options defined in the command language, 
used to request input/output redirection, background execution, and so 
forth. 

A sequence of commands can be stored in a command file - for inclusion into the command 
input stream with the built-in include . command command. A command file can be 
made into an executable script by using the make . script utility. 

An optional command history can be used - to record commands entered. One or more 
recorded commands may be re-executed. The built-in command 
list . last_commands shows the recorded commands; one or more of these recorded 
commands are redone with the redo . last_commands command. 

There is support for BiiN™/UX invocation command conventions - such as ar gv , ar gc , 
envp; see the BiiN™/UX User's Guide. 
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Why Use Commands? 

Commands provide an easy, standardized way to interact with the user: 

• Commands provide a common entry foraiat. 

• Commands are entered and confinned without program intervention, A complete, correct 
command is then available to the program. 

Programs Using the Command Service 

Most programs using the command service wiU be new utilities. 

Commands arc defined during program development. Each distinct function that the program 
performs should liave its own command. 

Commands arc grouped in command sets. Separate command sets may be defined for different 
program tasks, or for different user groups. 

Not all programs are suitable for command-oriented input Therc are several alternatives to 
using commands to control your program: 

menus Read menu item selections; see Chapter V-5. 

keyboard input Read the keyboard directly; see Chapter IV-5. 
graphics input Read the mouse's position and state. See TBD. 

V-1.U.2 Command Summary 

• Commands provide a consistent user control mechanism, used by all BiiN™ utilities. 

• A command consists of the command name, arguments if any, and optionally one or more 
control options. 

• The command service requires the user to enter a complete command; help is available for 
each command and each argument. Calls in the Command_Handler package retum the 
entered command values. 

• New commands are defined with the manage . commands command set in the 
manage . program utility. Each command definition is stored under a pathname. 

• Some commands are built-in; other commands are defined by programs using the command 
service (including the CLEX program itself). 

• Built-in commands are part of every command set. These commands are intercepted and 
processed by the command service itself. 

• Your program can request execution of a CLEX command, optionally in a new CLEX 
instance, using calls in the Command_Execution package. 

• Menus are another method for the user to control a program. See Chapter V-5 for more 
information about menus. 

V-1 .1 A Environment Service 

The environment service manages BiiN™ CL (Command Language) variables in active 
memory. A BiiN™ CL variable can contain a value of any CL type. Variables can be shared 
between jobs and processes in a session. 
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Figure V-1-4 shows how variables in passive store and active memory are related, and the 
order of evaluation for variables. 



Passive Store (manage. var_groups utility) 



System Variable Groups (/var_groups) 



User Variable Groups (~/var_groups) 



evaluation 



copied on 
reference 



Active Memory (Environment_Mgt calls) 



global (session) buffer 



local (job) buffer 



Figure V-1-4. Command Language Variables 



V-1.1 .4,1 Environment Variable Concepts 

• A command language variable - has a name, a type, a mode, and a value: 

name A CL string of letters and digits. 

type One of the six CL_Def s types: boolean, integer, range. 



mode 



value 



string, string list, or pointer. 

Either read_only, indicating that the variable can be read but not 
assigned, or read_write, indicating that the variable can be read or 
assigned a value. 

Any value of the appropriate type. 



• There are two kinds of variables - those dynamically created in active memory, using calls 
in Environment_Mgt (and the . variable commands built into the command 
service), and those defined in passive store, using the manage . var iable_group 
utility. 

• Variables in active memory - are dynamically created in one of two buffers: either a 

job-specific local buffer or the session-specific global buffer. 

Variables in passive store - are in system and user groups. System variable groups are 

stored in the / var_groups directory and can only be updated by the 
system administrator. User variable groups are stored in each user's 
~/var_groups, and are maintained with the 
manage . variable group utility. 
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- Sets of system or user variables - may be collected together in a group by giving them a 
group name. For example, cli . prompt is the prompt variable in the cli . group. 
Group variables may only be created with the manage . variable_group utility. 

- System variable groups apply to all sessions on this node. System variables arc created 
and maintained by the system administrator. System variables arc in pre-defined 
groups, stored in the system directory / var_groups. 

- User variable groups contain user-specific information, values, and defaults. User vari- 
ables arc crcated and maintained with the manage . var iable_group utility. User 
variables are stored in a "var_groups" directory in your home directory 
(~/var__groups). 

- Job variables arc crcated and used by jobs, in the global buffer. Job variables may be 
crcated and used either by calls to Envir onment_Mgt, or by programs using the 
Command_Handler package (programs with runtime commands). Subsequent jobs 
in this session inherit all existing job variables. 

- Local variables arc used like job variables, but only exist for the duration of a job. 
Local variables are stored in the local buffer. 

• Variable names are evaluated upwards until found - 

1. local buffer 

2. global buffer 

3. user variable groups (~ / var_groups directory) 

4. system variable groups (/ var_groups directory). 

• Each job has its own copy - of system, user, and job variables (global buffer), and local 
variables (local buffer). Referencing a user or system variable causes a copy of that vari- 
able to be created in the job's global variable birffer. Job variables may be created in either 
the global or local buffer. Local variables are created, set, and removed in the job's local 
variable buffer. 

• Subsequent jobs are affected by changes to the global buffer - since they inherit a copy of 
the current global buffer. 

• Changes only affect the job's copy of the variables - changes to stored (system or user) 
variables are oiily made in the job's global variable buffer. Use the 

manage . var iable_group utility to change system and user variables permanently, 

• Variables may also be created and changed - using four built-in commands common to 
CLEX and the command service: 

create . variable 

Creates a new local or global variable, optionally with an initial value. 

set . variable Sets a value into an active variable which has mode 

CL_Def s . read_write. 

remove . variable 

Removes a variable fi"om the local or global buffer. The version of the 
variable in passive storc is not affected. 

list . variable Lists the type, mode, name, and currcnt value of the specified variables 
or variable groups. 
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V-1,1.4.2 Environment Variable Summary 

• A variable has a name, a type, a mode and a value. The variable's type is one of the six CL 
types: boolean, string, .... The variable's mode is either read_only or 
read_write. The variable's value is of the appropriate type. 

• Command language (CL) variables control aspects of the current CLEX instance (such as 
message type and language) and contain information for use by jobs and programs (such as 
the current directory). 

• System and user environment variables in passive store are maintained by the 
manage . variable_group utility. 

• Variables in active memory are in either the local or global buffer. Stored variables are 
copied into the global buffer when referenced. 

• Global variables are inherited by subsequent jobs and processes in this session. 

• Variables may be read, set, and changed procedurally and interactively. Either call the 
environment service (Environment_Mgt), or enter one of the built-in . variable 
commands: create . variable, set . variable, list . variable, and. 
remove . variable. 

V-1.1.5 Menu Service 

Menus are available to a BiiN™ program. They are defined by the Window_Services pack- 
age. 

Menu definitions may be created procedurally with calls to Data_Def inition_Mgt. 

Figure V-1-5 shows a menu group in a window, with one of the menus currently selected. 
This figure also shows the relationship between the window service (which provides the menus 
and the window), the display access method (which returns the user's selection), and your 
BuN program. 
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Figure V-1-5. BiiN™ Application Program and Menus 
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V-1.1.5.1 Menu Concepts 

• A menu has a title and one or more menu items - the user selects a menu title, causing that 
menu to appear, and then selects one item from the menu. 

• Each menu is part of a menu group - a menu group contains one or more menus. 

• A window can have only one menu group enabled - several menu groups can be installed in 
one window, but only one menu group is enabled at any time. 

• Menu items may have associated "help" messages - the user can request an explanation of 
any menu item. 

• Menu items may be picked by the cursor or by index - to choose an item, the user enters the 
displayed item's index number, 

• Menu selection events - can be read by calling the character display access method 

(Character_Display_AM). 

V-1.1.5.2 Menu Summary 

• Menus provide a consistent, easy-to-use user interface. 

• A menu group contains one or more menus. Menus consist of a menu title and one or more 
menu items. 

• A window can have several menu groups installed, but only one menu group at a time can 
be enabled. 

• After a menu group is installed and enabled, menu selections and menu "help" messages 
are displayed without program intervention. 

V-1 .1 .6 Form Service 

The form service creates, modifies and executes interactive forais for structored data entry and 
display. 

A form displayed in a window resembles a form printed on paper. Unlike paper forms, the 
forms created and controlled by using the form service can be dynamically changed for various 
data input and display requirements. 

An example forai is shown in Figure V-1 -6. 
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Part ID: 


D€ 


iscription 








Location: 


Unit: each 
lb 

Usage this 

Usage this 

Usage last 


feet 
inch 

month: 

year: 

year: 


(circle 
one) 


Qty on hand: 




Reorder point: 








Reorder qty: 








Supplier ID: 








Average unit cost: $_ 
Last unit cost: $_ 
Date first activity: 
Date last activity: 


1 ♦ 
1 • 


Status: 















Figure V-I-6. Example Form 



The cursor, which marks the current position in the form, may be moved back a space to erase 
an incorrect character, or back to the previous field to reenter a value. The contents of part of 
the fomi can be altered depending on the value of a previously entered field. Intermediate 
values can be calculated and stored transparently until needed later by the forai. Even the 
order of execution of the fomi can be altered dynamically depending on the data entered. 

Creating an executable form involves: 

• Designing the forai's data and layout requirements 

• Generating a fonn definition with edit . f ormor define . standard_f orm 

• Creating a file of associated "help" messages 

• Writing a program to execute a form, which can include processing routines (called before 
or after a field), key catchers (called by individual key sequences), and key lists (for the key 
catchers) 

• Testing the form with the application. 

The form service (Form_Handler package) provides calls to: 

• Open and close a form 

• Execute a form 

• Modify data and control the execution network path 

• Manage form elements 

• Query the state of the form, a form element, or the last user interaction. 

The Chapter V-5.3 describes the various parts of an interactive form and how they are com- 
bined into a single, executable form. 
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text alphanumeric field 

I I 

Part ID: 3512734 Description: 1/2" aluminum conduit 



Location; 02-F12 
Qty on hand: 500 
Reorder point: 750 
Reorder qty: 2000 
Supplier ID: RohmCo 
Average unit cost ; $ 
Last unit cost : $ 



Unit: feet < overlaid enumeration 

Usage this month: 375 < numeric 

field 

Usage this year: 6250 

Usage last year: 9475 

StanEfCo < group 

1.86 

1.65 < numeric field 



Date first activity: 1985-06-25 < date field 

Date last activity: 1987-03-13 Status: REORDER 

Delete this part {press <Return> to affirm) ? DELETE 

I 
option field 



Figure V-1-7. Annotated Executable Form 



Fonn definitions arc created with the def ine_standard_f orm and edit . form utilities. 
A fonn definition may be derived fix)m a file's record definition. 

define . standard_f orm 

Creates the simplest, default fonn definition, given a data record defini- 
tion. 

edit . form Creates and modifies fonn definitions. Enables a programmer to design a 

form directly on the terminal screen and to define the properties for each 
form element as it is drawn and positioned. Detailed infonnation for using 
edit . form is given in the BiiN^ Systems Form Editor Guide. 

Application developers will normally use edit . form to create and update a form's defini- 
tion. Form definitions can also be created procedurally using Data_Def inition_Mgt. 



V-1.1.6.1 Form Summary 



• The form service builds upon the concept of a paper forai to provide interactive fomis 
capabilities on a terminal. 

• A form can be created with the edit . form or define . standard_f orm. 

• A forai may consist of the following fonn elements: 

- texts 

- screen fields 

- enumerations 

- subfonns: simple subforais and group subforms 



V-1-14 



Understanding Human Interface Services 



PRELIMINARY 

- piles 

- subprogram interfaces 

- processing routines 

- key catchers 

- key lists. 

• Variable length alphanumeric screen fields, and the screen elements containing them, can 
expand to accommodate data entered into the field. 



V-1.1.7 Report Service 



The report service provides formatted output from sets of records. A report is a printed or 
displayed document containing labelled data, often presented in hierarchical groups with sub- 
totals and totals. A typical report is shown in Figure V-1-8. 



Part ID 


Description 


Location 


Unit 


1234567 


wiring harness 


13-B27 


each 


3512734 


1/2" aluminum conduit 


02-F12 


feet 


4766117 


5/16" hex carriage bolt 


07-A02 


each 


7689482 


flexible control cable 


06-C13 


inch 



Figure V-1-8. Example Report 



V-1.1.7.1 Report Concepts 



The report service requires a record definition that describes the data to be printed. The report 
definition can be created from an existing file's record definition. 

The format of a standard report page is shown in Figure V-1-9. 
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1 System date 


1 


1 

Page Number 1 
1 


1 — —^ , 

1 Page Heading I 

1 — _____ __ 1 


1 field 11.. 


. 1 field i 1 . 


1 
. 1 field n I 


1 _ 1 


1 II III! 


1 ... 1 


1 Page Footing I 



heading 



page 
body 
area 



I footing 



Figure V-1-9. Layout of a Standard Report Page 



There are two methods for creating and modifying report definitions: by using interactive 
utilities (define . standard_report and edit . report) and procedurally, using 

Data_Def inition_Mgt. 

define . standard_report 

Creates the simplest, default report definition, given a data record defini- 
tion. 

edit, report Creates and modifies report definitions. See the BUN™ Systems Reports 
Guide for detailed information on edit . report. 

Application developers will normally use edit . report to create and update a report's 
definition. Report definitions can also be created procedurally using 

Data_Def inition_Mgt. 

Reports are composed of the following components: 



Report Details 



Report Parts 



A report detail is the smallest printable piece of a report. There are three 
kinds of details: 

• Data detail 

• Computed detail 

• Text detail. 

A report consists of the following logical report parts, each consisting of 
one or more report details: 

• Record print layout 

• Report heading 

• Page heading 

• Page footing 
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• Control group heading (only if a control group hierarchy is defined) 

• Control group footing (only if a control group hierarchy is defined). 

Printing a Report 

Reports are either printed or displayed depending on the type of output device, that is, depend- 
ing on whether the physical output device is a printer, a terminal, or some other output device 
which supports character display I/O. 

Two methods are available for printing (or displaying) a report: procedurally, by calling the 
Report_Handler . Print procedure, and interactively, by using the print . file utility. 

Both of these methods read data records from the report input device, format each line of the 
report, and write the result to the given report output device. 



V-1.1.7.2 Report Summary 

• A report is produced from sets of input data records, formatted as desired, often presented 
in hierarchical groups with subtotals and totals. 

• There are two utilities for creating and modifying report definitions: edit . report and 
define . standard_report. 

• The report service (Report_Handler) provides calls to associate a report with an input 
and output device, print a report, and control error handling. 

• A report can be printed or displayed either procedurally, with the 
Report_Handler . Print procedure, or interactively, using the print . file utility. 

V-1 ,2 Summary 

• Human Interface Services is composed of five services: 

command service Given a command definition, parses and retums invocation and runtime 
commands. 

environment service 

Reads, writes, and creates BiiN CL variables. 

menu service Given a menu definition, provides on-screen menus (lists of menu 

items). 

form service Given a form definition, controls execution of a data entry or display 

form. 

report service Given a report definition, produces a printed report from data records. 

• These services perform most of the processing necessary for user interaction, including 
enforcement of input requirements and automatic display of "help" messages. 

• A default data entry form, and a default report, can be automatically created from a file's 
record definition. 

• Human Interface Services provide a complete, consistent user interface, shared by BiiN™ 
system utilities and CLEX itself. 
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TM 

This chapter describes how to use the various parts of the BiiN system software to create a 
simple application program. The example is an inventory program controlled with menus, 
which gets structured input from a user, updates the inventory files, displays formatted infor- 
mation, and prints an inventory report. 

The complete source code for this example program is listed in Appendix A. 

Packages Used: 

Ac ce s s_Mgt Interface for checking or changing rights in access descriptors. 

Char act er_Display_AM 

Provides device-independent I/O to character display devices such as 
printers, plotters, and windows on character and graphics terminals. 

Data_Definition_Mgt 

Manages data definitions (DDefs). This interface is a symbol table for the 
development of a DDef compiler. 

Direct or y_Mgt Manages directories and directory entries. 

File_Admin Administers files. 

Form_Handler Provides calls to process, control, and change forms. 

Message_Services 

Provides calls to write messages from message files, message stacks, or 
message blocks. 

P r o c e s s_Mgt Provides public operations on processes. 

Record_AM Provides device-independent record I/O. 

Report_Handler 

Provides calls for initializing and printing a report 

Window_Services 

Provides windows on character and graphics terminals, including pull- 
down menus. 



Figure V-2- 1 shows the external relationships of a BiiN program to its terminal (windows), 
its control input (menus), its notes, warnings, and help information (messages), its data input 
and display (forms), and its printed output (reports). 

TM 

As with most computer systems, the BiiN OS (CLEX) invokes the program and passes m 
invocation command arguments. And, as usual, the program interacts with files. 



V-2-2 Creatin! 



PRELIMINARY 




Form 



Figure V-2-1. Typical BiiN™ Application Program 



A BiiN program relies on various system services. Each of these services are described in 
other chapters in this BiiN^IOS Guide. 

. TM 

BuN provides several ways of interacting with users via terminals: 

• Windows, to reserve an area of the terminal screen for a program. A program may open 
any number of windows. Usually, there is one main window for user input and data dis- 
play, and optionally a small window for help and error messages. The message window 
may be the already existing system message window. 

• Messages, to display a text with up to five parameters (such as file name and error number) 
in a user-selected language and format (short, long, help). 

• Menus, to allow a user to select an item from a list. The menu group ID, menu ID, and 
menu item ID numbers are returned to the program. 

• Commands, to aUow the user to control a program. See Chapter V-3, "Building New 
Commands", for more information. 
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• Forms, to enforce structured data entry. Each data entry field may have an associated help 
message. Forms are also used to display structured data. 

• Reports, to produce a formatted display of a set of data records. 
A BiiN™ program itself is insulated from changes to: 

• Message texts and variants - only the message file itself needs to be updated. Message 
variants are automatically displayed in the user's desired language and format 

• Changing languages for menus or commands - if the numeric menu and command IDs 
remain the same. 

• Form layouts - the displayed formats may be changed; as long as no fields are added or 
deleted, the program will not know the difference. 

• Report layouts - the report formatting, headings, control breaks, footings, and so forth, can 
be changed. 

The following tasks are described in this chapter: 

• How to create and read the program's invocation command. 

• How to create and display messages. 

• How to use windows, menus, and forms to interact with the user. 

• How to read, write, and update records in named files. 

• How to print a report from a file and how to sort records from a file and then print a report 
from the sorted records. 



V-2.1 Concepts 



TM 



V-2.1. 1 Designing a BiiN Program 

As with any program on any system, a complete program description is the first step when 
creating an applicatioa For a BiiN™ program, this program description includes: 

• Whether it's to be a batch or interactive program, 

• Whether to use a menu-driven or command-driven user control interface, 

menu selections Simplest for the user - define menu groups, individual menus and menu 
items 

runtime commands Provides more control - define sets of commands, command names, 
types and numbers of command arguments. 

• What input and output files are required, including the record layout of the program's files, 

• Design of data entry and display forms, if used, 

• What data manipulation is desired, and 

• What types of reports are to be produced. 

Once the main files' record layouts have been specified, the specification of default data input 
forms and reporte can be done automatically (see the next section, "Defining the Application's 
Data Structure"). 
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V-2.1 .2 Defining the Application's Data Structure 

The data definition (record layout) of a file can be used to automatically generate input and 
display forms and report definitions (DDefs). The resulting form and report DDefs can then be 
edited with the corresponding editor utilities to create a desired format. 

Tools Used: 

TBD Creates a record DDef for a file. 

define . standard_f orm 

Creates a standard form DDef from a record DDef. 

edit . form Edits a form description's layout and screen properties. 

define . standard_report 

Creates a standard report DDef from a record DDef. 

edit . report Edits a report description. 



Figure V-2-2 shows the relationship between a file's record DDef, the standard form layout, 
and the standard report layout 



type pQrts_record_type is 



record 
partJD 
desc 
unit 
location 



System _Defs.textfpart_ID_ienqth; 
Systenn_Defs.text(desc_length); 
System _Defs.textrunit_length); 
System _Defs.text(loc_length); 



end record; 



Part ID . 

De3c 

Unit 

Location 



Form 



Report 
Editor 




Port 


Desc 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx 


xxxx 



Report 



Form DDef Record DDef Report DDef 

Figure V-2-2. File Data Definition and Associated Forms and Reports 



V-2.1 .3 Example Program Overview 

The example program is a menu-driven inventory control program. The menu group's title 
line is used to select one of six menus. Using selections from the menus, the user may inquire 
about parts on file, enter a new part ID and description, change part information, print one of 
two inventory reports, and re-index the parts file. 



Creating a BiiN™ Application Program 



V-2-5 



PRELIMINARY 

The program has an associated message file which contains the texts of all inforaiation, warn- 
ing, and error messages. Help texts are stored within the menu and form definitions. 

Menus 

The menus in the example program are shown in Figure V-2-3. 



Inquiry 



Posting 



Update Reports 



Housekeeping 



Exit Program 



Menu Group 



Inquiry Menu 



1. Search by Part ID 

2. Search by Part Description 

3. Exit Menu I 



I Posting Menu 



Receipts 
Issues 
Returns 
Spoilage 
Journal Entry 
Exit Menul 



I Update Menu 



1. Add Part 

2. Change Part Information 

3. Delete Part 

4. Exit Menu 



I Reports Menu | 



1. Print Report by Part 

2. Print Report by Location 

3. Exit Menu i 



Housekeeping Menu 



1. Index Parts File 

2. Exit Menu 



->• menu selection enabled in example program) 



Figure V-2-3. Example Program Menus 



Data Files 

There are two data files used by this program: the inventory parts file, indexed by part ID, and 
the log file, where records of updates and changes to the parts file are written. 



The parts file record layout, in Ada, is: 
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(from Inventory_Files specification) 



244 
245 
246 
247 
248 
249 
250 
251 

254 
255 

259 
260 
261 
262 
263 

266 

269 

270 

272 
273 

275 
276 

278 

280 
281 
282 
283 

285 
286 
287 
288 
289 
290 
291 

294 
295 

298 
299 

302 



subtype part_ID_type is System_Defs .text ( 
part_ID_length) ; 

subtype supplier_ID_type is System_Defs .text ( 
supplier_ID_length) ; 

subtype location_type is System_Defs.text ( 
loc_length) ; 

subtype qty_type is System. ordinal 
range . . 9_999_999; 

subtype cost_type is float 

range .0 . . 99_999_999 . 99; 

type supplier_array_type is 

array (1 . .max_suppliers) of supplier_ID_type; 

type parts_record_type is 



record 

part_ID : 

desc: 

desc_length> 

unit: 

unit_length) 

location: 

qty_on_hand : 
reorder jpoint : 
reorder_qty : 
suppliers : 



part_ID_type ; 
System_Def s . text { 

System_Def s . text { 

location_type; 

qty_type; 
qty_type; 
qty_type; 
supplier_array_type; 



usage_this_month: qty_type; 

usage_last_month: qty_type; 

usage_last_year : qty_type; 

avg_unit_cost : cost_type; 

last_unit_cost : cost_type; 
date_f irst_act : 

Timing_Conversions.numeric_time; 

date_last_act : 

Timing_Conversions.numeric_time; 

status : System_Def s , text ( 

status length) ; 



end record; 



The log file record layout, in Ada, is: 
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(from Inventory Files specification) 



316 
317 

319 

321 

323 
324 
325 
326 
327 
328 
329 
330 

332 

333 

335 

337 
338 

340 
341 

343 

346 
347 

350 

353 



type action_type is ( 
create, 

update, 

. delete, 

receipt, 
issue, 
returns, 
spoilage, 
journal) ; 

type log_record_type is 



record 

part_ID : 

action: 
time: 



part_ID_type ; 
action_type; 



Timing_Conversions.numeric_time; 

doc_number: System_Defs.text { 
doc_length) ; 



qty: 



qty type; 



job_ID: System_Defs.text ( 
job_length) ; 

supplier_ID: supplier_ID_type; 

end record; 



Program Source Code Files 

A typical menu-driven application program has the following outline: 

Setup Open a window for this program, open the necessary files, display the 

main menu group. 

Input Get a menu selection from user, get necessary data for operation (input 

directiy from user, fiom a form, or from a file). 

Processing Perfomi the selected operation. 

Output Display information in program window, update files, print a report. 

Termination Qose files, deallocate objects, close the program's window. 

The example program is organized into the one main procedure and six Ada packages. Each of 
the packages collects the procedures related to a given service area: windows, files, menus, 
forms, and reports. The relationship between these parts of the example program are shown in 
Figure V-2-4. 
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lnventory_nnaln 
(inventory_main.sb) 



Inventory Messages 
(i_nnsgs.ms) 



Inventory Inventory 
Windows Files 


Inventory 
Menus 


(i_wlndows.s) (l_files.s) 
(i_windows.b) (l_files.b) 


(i_nnenus.s) 
(l_menus.b) 




Inventory Inventory 
Fornns Reports 




(l_forms.s) (i_reports.s) 
(i_forms.b) (l_reports.b) 


Figure V-2-4. Example Program Source Files 



Setup 

The following program fragment shows how the example program sets up its windows, opens 
its files, and prepares for menu input 

(from Inventory_Main) 

29 procedure Inventory_main 

38 is 

97 begin 

101 Invent ory_Windows .Open_program_windows; 

112 Inventory_Files .Open_parts_f ile; 

119 Inventory_Menus . Set_up_menu_group; 



125 
126 
127 
128 
129 



Character_Display_AM. Ops . Set_input_type_mask ( 

opened_dev => Inventory_Windows .main_window, 
new_mask => Terminal_Defs.input_type_mask' ( 
Terminal_Defs.menu_item_j3icked => true, 
others => false) ) ; 



Processing 



The following program fi-agment shows the example program's main processing loop: read the 
menu selection, then perform the appropriate action (possibly just exit program). 
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(from Inventory_Main) 

134 loop 

13 9 Character_Display _AM. Ops. Read { 

140 opened_dev => Inventory_Windows .main_window, 

151 case menu_select .menu is 
152 

153 when Inventory_Menus.inquiry_menu_ID => 

154 Inventory_Menus .Process_inquiry_menu ( 

155 selection => menu_select .item) ; 

157 when Invent ory_Menus. post ing_menu_ID => 

173 when Inventory_Menus.exit_menu_ID => 

174 EXIT; 

179 end case; ■ — "case me nu_s elect. menu is" 

180 

181 end loop; 

Termination 

The following program fragment shows how the example program closes both its windows 
(which disables enabled menus) and its files. 

(from Inventory Main) 



186 Inventory_Files.Close_parts_file; 

200 Inventory_Windows 

201 

202 end Inventory_main; 



200 Inventory_Windows .Close_program_windows; 
201 



V-2.2 Techniques 

After reading this section, you will be able to: 

• Interact with the command line: 

- Create and store an invocation command definition and argument definitions 

- Read command line argument values. 

• Set up a window for a program 

• Accept and process user menu selections from menus 

• Display a message 

• Set up a form and get the user's input data 

• Display a form containing program-generated information. 

• Update a given record fiom a file 

• Print a report fix)m a file. 

V-2.2.1 Creating and Processing the Invocation Command 
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Calls Used: 

manage .program 

Creates command definitions. 

Command_Handler . Open_invocation_command__processing 
Opens die invocation command device for processing. 

Command_Handler . Get_argument_type 
Returns argument values. 

Command_Handler . Close 

Qoses the opened invocation command input device. 

Define your program's invocation command name and the necessary arguments. Use the 
manage . commands command set in the manage . program utility to define the program's 
invocation command. 

Call Command_Handler . Open_invocation_command_processing to open the in- 
vocation command input device. The invocation command has already been parsed, and calls 
to Command_Handler . Get_argumentjype will return the invocation argument values. 

When you are through reading argument values, close the opened invocation command input 
device by calling Command_Handler . Close. 

See Chapter V-3 for more information on processing commands. 

V-2.2.2 Using Windows in a Program 

Calls Used: 

Character_Display_AM . Get_device_ob ject 
Returns the object underlying a device. 

Process_Mgt . Get_process_globals_entry 

Returns process global variables; in this case, we are looking for the stan- 
dard input device. 

Window_Services . Ops . Create_window 

Creates a new window with a given size and positioa 

Window_Services . Ops . Get_terminal 

Returns an AD to the terminal on which an existing window is installed. 



The following program fragment shows how the example program sets up its main window. 
The program assumes that the standard input, on entry, is fiom a window. 

First, you need to find that opened window, then the actual window, then the terminal display- 
ing the actual window. Then you can set up the new program window on that terminal. 
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(from Inventory_Windows specification) 

27 inain_window_size: Terminal_Def s.point_info := { 

28 80,20); 

31 main_buffer_slze: Terminal_Defs.point_info := ( 

32 80,20); 

35 main_window_pos : Terininal_Defs.point_info := { 

36 1,1); 

(from Inventory_Windows body) 

12 procedure Open_program_windows 

21 is 

22 old_opened_window: Device_Defs .opened_device; 

23 old_window: Device_Defs. device; 

24 underlying_terminal: Device_Defs. device; 
25 

26 begin 

31 old_opened_window := 

32 Process_Mgt .Get_process_globals_entry ( 

33 Process_Mgt_Types.standard_input) ; 

37 old_window := Byte_Stream_AM.Ops.Get_device_object ( 

38 old_opened_window) ; 

43 under lying_terminal := 

4 4 Window_Services.Ops.Get_terminal ( 

4 5 old_window) ; 

4 9 main_window := Window_Services.Ops.Create_window{ 

50 terminal => underlying_terminal, 

51 pixel_units => false, 

52 — characters, not pixels 

53 fb_size => main_buf fer_size, 

54 desired_window_size => main_window_size, 

55 window_pos => main_window_pos, 

5 6 view_pos => 

57 Terminal_Defs.point_info' (1,1)); 

71 end Open_program_windows; 

V-2.2.3 Processing a Menu Selection 

Calls Used: 

Character_Display_AM . Ops . Set_input_type_mask 
Sets the allowable input events for a window. 

Char act er_Display_AM . Read 

Reads an event from a terminal. 

Data_Def inition_Mgt . Retrieve_DDef 

Retrieves an object's DDef, given the object's AD. 

Direct or y_Mgt . Retrieve 

Retrieves a stored object's AD, given the object's pathname. 

Window_Services . Ops . Install_menu_group 
Installs a menu group in a window. 

Window_Ser vices . Ops . Menu_group_enable 
Enables an installed menu group. 
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This technique shows how to: 

• create a menu (using a utility) 

• install and enable a menu 

• read the user's menu selection 

• process a menu's selections. 

Creating Menus 

Define the menu titles and menu item texts, then the menu groups. 

Create each menu group, using the TBD (edit .menu) utility. 

1 . Create a null menu group to contain the menus. 

2. Add each menu and its title to the menu group. 

3. Add each menu item and its text to each menu. 

Store the menu group DDef under a pathname. 
Installing and Enabling a Menu Group 
Retrieve the menu group's DDef. 

Install and enable the menu group, using calls in Window_Ser vices: 

1 . Install_menu_group - install the menu group in an open window. 

2. Menu_group_enable - enable a menu group for user selection. 

(from Inventory_Menus specification) 

74 inv_menu_group_ID : constant 

75 Terminal_Defs.menu_group_ID := 1; 

(from Inventory_Menus body) 

30 menu_group_DDef _AD : Data_Def inition_Mgt .DDef_AD; 

33 menu_group_node : 

34 Data_Definition_Mgt .node_reference; 

46 menu_group_DDef_AD := DDef_from_untyped ( 

4 7 Directory_Mgt .Retrieve ( 

4 8 name => menu_group_DDef_path) ) ; 

53 menu_group_node := Data_Def inition_Mgt . 

54 Retrieve_DDef ( 

55 DDef => menu_group_DDef_AD, 

5 6 name => menu_group_DDef_root_name) ; 

61 Window_Services .Ops . Install_menu_group ( 

62 window => Inventory_Windows . 

63 main_window, 

64 menu_group => menu_group_node, 

65 ID => inv_menu_group_ID) ; 

6 9 Window_Services . Ops . Menu_gr oup_enable ( 

70 window => Inventory_Windows . 

71 main_window, 

72 menu_group => inv_menu_group_ID, 

73 enable => true) ; 
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Reading a Menu Selection 
To read a menu selection: 

• Set the input type mask for the menu group's window to include 

Terminal_Def s . nienu_item_picked, 



• Wait for an input event at the terminal, and 

• Read the menu selection values (menu group ID, menu ID, and menu item ID numbers). 

(from Inventory_Main) 

79 menu_select : Terminal_Defs.menu_se lection, • 
86 event_type: Terminal_Def s. input_enum; 
90 event_nuin: System, ordinal; 

125 Char act er_Display_AM. Ops . Set_input_type_mask ( 

126 opened_dev => Inventory_Windows.main_window, 

127 new_mask => Terminal_Defs .input_type_mask' ( 

128 Terminal_Defs.menu_item_picked => true, 

129 others => false)); 

139 Character_Display_AM. Ops. Read { 

140 opened_dev => Inventory_Windows .main_window, 

141 buffer_VA => menu_select' address, 

142 max_e vents => 1, 

143 max_bytes => 0, 

144 block => true, — Wait . . . 
14 5 type_read => event_type, 

14 6 num_read => event_num) ; 

151 case menu_select .menu is 
152 

153 when Inventory_Menus. inquiry_menu_ID => 

154 Inventory_Menus.Process_inquiry_menu ( 

155 selection => menu_select .item) ; 

Example Menu Processing Routine 

Use the menu and item selection nimibers (for example, in a case statement) to determine the 
appropriate action. 

Define the menu and item numbers: 
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(from Inventory_Menus specification) 

80 inquiry _menu_ID : constant 

81 Terminal_Defs.menu_ID := 1; 
82 

83 posting_menu_ID: constant 

84 Terminal_Defs.menu_ID := 2; 
85 

86 update_menu_ID: constant 

87 Terminal_Def s .menu_ID := 3; 
88 

89 report_menu_ID: constant 

90 Terminal_Defs.menu_ID := 4; 
91 

92 housekeeping_menu_ID: constant 

93 Terminal_Defs.menu_ID := 5; 
94 

95 exit_menu_ID: constant 

96 Terminal_Defs.menu_ID := 6; 
97 

98 — Inquiry menu items 

99 inq_by_part_item: constant 

100 Terminal_Defs.menu_item_ID := 1; 

101 inq_by_desc_item: constant 

102 Terminal_Defs.menu_item_ID := 2; 

103 inq_exit_item: constant 

104 Terminal_Defs.menu_item_ID := 3; 

Process the menu's selections: 

(from Inventory_Menus body) 

79 procedure Process_inquiry_menu ( 

80 selection: Terminal_Defs.menu_item_ID) 

81 — Selection made in this menu. 

82 is 

8 6 begin 
87 

88 case selection is 
89 

90 when inq_by_part_item => Inventory_Forms . 

91 Process_inquiry_form; 
92 

93 when inq_by_desc_item => 
94 

95 Message_Services.Write_msg( 

96 msg_id => no_selection_code, 

105 when inq_exit_item => 

106 return; 
107 

108 when others => null; 

109 

110 end case; 

111 

112 end Process_inquiry_menu; 

V-2.2.4 Displaying a IVIessage 

Calls Used: 

Message_Services .Write_msg 

Writes a specified message and its parameters to an opened device. 
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Messages are used to display status information and for warnings and errors. 

To use messages, you must create a message file containing the texts for all your program's 
messages. This is done with the manage .messages utility (or the manage .messages 
command set in the manage . program utility), using your message definition commands. 

The program need only know the message file's pathname: 

(from Inventory _Messages specification) 

24 message_file: constant System_Defs.text_AD := 

25 new System_Defs.text' ( 

26 31, 31, "/example/inventory/message_f ile") ; 

32 message_object: constant System. untyped_word := 

33 System. null_word; 
34 

35 pragma bind {message_object, 

36 "inventory_messages.message_f ile") ; 

A program refers to a message by an Incident_Def s . incident_code, which deter- 
mines the message file, the message index numbers (module number and message niraiber), 
and the severity level. 

The message definition commands can be stored in your source file near the 
Incident_Def s . incident_code declarations. The manage . program utility can ex- 
tract message definition commands from your source file, to create the message file. 

To define a given message: 

(from Inventory_Messages specification) 

30 module: constant := 4; 

set. language : language = English 
create. variable module rvalue = 4 

:ion_code; constant 
Incident_Defs.incident_code := ( 
message_object => 

Invent ory_Messages.message_object, 
module => module, 

number => 1, 

severity => 

Incident_Defs. warning) ; 

store : module = $module : number = 1\ 
:msg_name = no_selection\ 
: short = "Selection $pl<selection 

number> is not implemented." 

To write a message to the default message device (window): 

(from Inventory_Menus body) 

80 selection: Terminal_Defs.menu_item_ID) 

95 Message_Services.Write_msg( 

96 msg_id => no_selection_code, 

97 paraml => 

98 Incident_Defs .message_j>arameter ( 

99 typ => Incident_Defs.ord, 

100 len => 0) ' ( 

101 • typ => Incident_Def s.ord, 

102 len => 0, 

103 o val => selection) ) ; 
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V-2.2.5 Getting Data from a Form 

Calls Used: 

Directory_Mgt . Retrieve 

Retrieves a stored object's AD, given the object's pathname. 

Form_Handler . Clear 

Qears a fonn from its window. 

Form_Handler .Close_f orm 

Qoses and deallocates an opened fonn. 

Form_Handler .Fetch_value 

Gets a value from a field in a fonn. 

Form_Handler . Get 

Displays a form for user input; returns when the fonn is finished. 

Form_Handler .Open_f orm 

Opens a forni for processing. 

Record_AM . Open_by_name 

Opens a device for record access, given the device's pathname. 

Record_AM . Ops . Close 

Qoses an open device. 

Record_AM . Ops . Update 

Updates (writes) a record to an open device. 



Define the fonn layout, field names, and field types. Create the fonn DDef with the 
define . standard_f orm utility, and/or the edit . form utility. Store the forai's DDef 
under a pathname. 

Get the stored fonn DDef by calling Directory_Mgt . Retrieve with the fomi's path- 
name, then converting the returned untyped word to a DDef AD using an instance of 
Unchecked_Conver sion. Open the fonn by calling Form_Handler . Open_f orm. 
(from Inventory_Forms body) 

40 openeci_form: Form_Defs.opened_form_AD; 

4 4 opened_forin := Form_Handler .Open_form { 
45 DDef => DDef_from_untyped( 

4 6 Directory_Mgt .Retrieve ( 

4 7 name => form_pathname) ) ) ; 

If the forni has groups or piles to be set, call 

Form_Handler . Great e_group_instances as necessary. 

(from Inventory_Forms body) 

406 when Invent ory_Menus.update_add_i tern => 
407 

408 Form_Handler .Create_group_instances ( 

409 opened_form_a => opened_form, 

410 group => update_add, 

411 number_of_instances => 1) ; 

If desired, open the form for record access: 
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(from Inventory_Forms body) 
377 opened_record_form: Device_Def s.opened_device; 

432 opened_record_form := Record_AM.Open_by_naine ( 

433 name => update_form__pathname, 

434 input_output => Device_Defs .inout) ; 

Display the form and allow user data entry, by calling Form_Handler . Get, specifying the 
form and the window where the forni is to be displayed: 

(from Inventory_Forms body) 

439 form_status := Form_Handler .Get { 

440 opened_form_a => opened_form, 

441 opened_window_a => 

442 Inventory _Windows.main_window) ; 
443 

444 if form_status /= Form_Defs. finished then 

Fetch data from fields in the fonn by calling Form_Handler . Fetch_value: 

(from Inventory_Forms body) 

451 Form_Handler .Fetch_value ( 

452 opened_form_a => opened_form, 

453 element => part_ID_f ield, 

454 subunit => System_Defs.null_text, 

455 — added subunit; value correct? 

456 value_buffer_VA => part_ID' address, 

457 value_length => part_ID' size/8, 

458 value_t => 

459 Data_Def inition_Mgt .t_string, 

460 element_value_length => length, 

461 empty => empty) ; 
462 

463 if empty then 

Read a data record from the fonn by calling Record_AM . Ops . Read: 

(from Inventory_Forms body) 

371 parts_record: 

372 Inventory_Files.parts_record_type; 

380 length: System. ordinal; 

495 length := Record_AM. Ops .Read ( 

496 opened_dev => opened_record_f orm, 

497 buffer_VA => parts_record' address, 

498 length => parts_record' size/8) ; 

Clear the form from the window by calling Form_Handler . Clear_f orm. Close the form 
by calling Forni_Handler . Close_f orm: 
(from Inventory_Forms body) 

553 Form_Handler .Clear ( 

554 opened_form_a => opened_form) ; 
555 

556 Form_Handler .Close_form( 

557 opened_form_a => opened_form) ; 

Close record access to the form, if opened: 

(from Inventory_Forms body) 

561 Recor d_AM. Ops .Close ( 

562 opened_dev => opened_record_f orm) ; 
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V-2.2.6 Displaying Data Using a Form 

Calls Used: 

Directory_Mgt . Retrieve 

Gets a stored object's AD, given its pathname. 

Form_Handler . Clear 

Qears a fonn from its window. 

Form_Handler . Close_f orm 

Qoses and deallocates an opened form. 

Form_Handler . Open_f orm 

Opens a form for processing. 

Form_Handler . Put 

Displays a read-only fonn. 

Forin_Handler . Store_value 

Assigns a value to a field in an opened form. 

Record_AM . Open_by_name 

Opens a device for record access, given the device's pathname. 

Record_AM . Ops . Close 

Qoses an open device. 

Record_AM . Ops . Update 

Updates (writes) a record to an open device. 



This section describes how to use a form to display structured information. 

Define and create the form, retrieve and open the form's DDef, and set any necessary groups 
or piles, as described in the previous section, "Getting Data from a Form". 

If the form has been opened for record access (see previous section), write a data record into 
the form by calling Record_AM . Ops . Update: 
(from Inventory_Forms body) 

371 parts_record: 

372 Inventory_Files .parts_record_type; 

476 Record_AM.Ops.Update( 

477 opened_dev => opened_record_form, 

478 buffer_VA => parts_record' address, 

479 length => parts_record' size/8) ; 

Store data directly into individual fields in the form by calling 

Form Handler .Store value: 
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{from Inventory_Forms body) 

276 Forin_Handler.Store_value ( 

277 opened_form_a => opened_form, ^ 

278 element => desc_field, \ 

279 subunit => System_Defs.null_text, 

280 — added subunit; value correct? 

281 value_buffer_VA => 

282 parts_record.desc' address, 

283 value_length => 

284 parts_record.desc' size/8, 

285 value_t => 

286 Data_Definition_Mgt .t_string) ; 

Display the form and its contents by calling Form_Handler . Put, specifying the form and 
the window where the form is to be displayed. 

Clear the form from the window by calling Form_Handler . Clear_f orm, then close the 
form by calling Form_Handler . Close_f orm. 



V-2.2.7 Updating a File 



Packages Used: 



Access_Mgt .Permits 

Checks an object for given access rights. 

Directory_Mgt . Retrieve 

Returns an AD to an object, given a pathname. 

Record_AM . Keyed_Ops . Read_by_key 

Reads a record from an opened indexed device, given the index key value. 

Record_AM . Keyed_Ops . Update_by_key 

Updates a record in an opened indexed device, given the index key value. 

Record_AM. Ops . Close 

Qoses an opened device. 

Record_AM . Ops . Insert 

Inserts a record into an opened device. 

Record_AM . Ops . Open 

Opens a given device for record input or output, given a device AD. 

Record_AM . Ops . Open_by_name 

Opens a given device for record access, given a device's pathname. 



This section briefly describes how to use the filing service to update records in a file. For more 
information and procedural examples, see Chapter IV-9, "Using Record I/O with Structured 
Files". 

1. Define the file's record layout and then create the file's record DDef. This can be done 
procedurally using calls to Data_Def inition_Mgt. Store the file and its record DDef 
imder pathnames. 

2. Open the file by calling Record_AM . Ops . Open or Record_AM . Open_by_name. 

3. Read/write/rewrite records: 
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• Ifthe file is indexed: 

read a record Get the index key value of the desired record, and caU 

Record_AM . Keyed_Ops . Read_by_key. 

write a record Set the record value, then call Record_AM . Ops . Insert. 

rewrite a record Set the record value, then caU 

Record_AM . Keyed_Ops . Update_by_key. 

• If the file is not indexed: 

read a record Set the record pointer with Record_AM . Ops . Set__po sit ion, 
then read the record with Record_AM . Ops . Read. 

write a record Write the record with Record_AM . Ops . Insert. 

rewrite a record Rewrite the record with Record_AM . Ops . Update. 

4. Qose a file by calling Record_AM . Ops . Close. 

V-2.2.8 Printing a Report from a Fiie 

Calls Used: 

Byte_Stream_AM . Open_by_name 

Opens a device for byte stream access, given the device's pathname. 

Directory_Mgt .Retrieve 

Retrieves an object, given the object's pathname. 

Record_AM . Open 

Opens a file or device for record access. 

Record_AM. Ops. Close 

Qoses an opened file or device. 

Report_Handler . Initialize 

Initializes an opened report, given the report DDef and the input and out- 
put devices. 

Report_Handler .Print 

Prints an initialized report. 



This technique shows how to produce a given report fi-om a file to an output device. 
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Parts File 



(partJD) 

abc453-69 
def3-3-4 
xyz7445 
zzz0123x 



(desc, loc, unit) 

first part, sheifS, ton 
motor mount, bin106, each 
some part, bin41, each 
another part, bin12, foot 



Part ID 

abc453-69 
def3-3-4 
xyz7445 
zzz0123x 



Report by PartJD 



Description 

first part 
motor mount 
some part 
another part 



Location 

shelf6 
binlOe 
bln41 
bin12 



Unit of 
Measure 

ton 
each 
each 
foot 



Figure V-2-5. File and an Associated Report 



Create the report itself: 

• Given the previously created file's record DDef, use the define . standard_report 
utility and/or the edit . report utility, to create the desired report fonnat 

• Store the report DDef under a pathname. 

Open the desired input file, by calling Recor d_AM . Ops . Open. 

• To select a range of records in an indexed file for inclusion in the report, caU 
Record_AM . Keyed_Ops . Set_key_range with the appropriate first and last key 
values. 
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(from Inventory_Reports body) 

5 6 procedure Print_report_by_part ( 

57 , output_dev_pathname : System_Defs.text) 

65 is 

66 

67 opened_output : Device_Defs .opened_device; 

70 report_DDef: Data_Definition_Mgt .DDef_AD; 

73 initialized_report : Device_Def s.opened_device; 

7 6 local_parts_file: Device_Defs. device := 

77 Record_AM.Ops.Get_device_object ( 

78 Inventory_Files.parts_file) ; 

81 opened_local_parts_file: 

82 Device_Defs .opened_device; 

89 begin 

94 opened_local_parts_file := Record_AM.Ops.Open ( 

95 dev => local^arts_file, 

96 input_output => Device_Defs .input, 

97 allow => Device_Def s. readers ) ; 

Open the desired output device (must support the byte stream access method) by calling the 
appropriate Open: 

• For terminal output, call Character_Display_AM . Open. 

• For printer or file output, call By te_S tr eam_AM . Open. 

(from Inventory_Reports body) 

102 opened_output := Byte_Stream_AM.Open_by_name ( 

103 name => 

104 output_dev_pathname, 

105 input_output => 

106 De vice_De f s . output ) ; 

Get the report DDef by calling Directory_Mgt . Retrieve with the stored DDef s path- 
name. You will then have to convert the Retrieved untyped word into a DDef AD, by 
calling an instance of Unchecked_Conversion. 

(from Inventory_Reports specification) 

55 report_by_part_DDef_str : constant string := 
5 6 "/example/inventory/DDefs/report_by_j>art"; 

60 report_by_part_DDef_pathname: 

61 System_Defs.text ( 

62 report_by_part_DDef_str' length) := ( 

63 report_by_part_DDef_str' length, 

64 report_by_jjart_DDef_str' length, 

65 report_by_part_DDef_str) ; 

(from Inventory_Reports body) 

111 report_DDef := DDef_f rom_untyped ( 

112 Directory_Mgt .Retrieve ( 

113 name => report_by_part_DDef_pathname) ) ; 

Initialize the report handler by calling Report_Handler . Initialize with the report 
DDef, and the opened input and output devices. 
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(from Inventory_Reports body) 

119 initialized_report := Report_Handler. Initialize ( 

120 description => report_DDef, 

121 input => opened_local_parts_f ile, 

122 output => opened_output) ; 

Print the report by calling Report_Handler . Print with the initialized report. 

(from Inventory_Reports body) 

127 Report_Handler. Print ( 

128 report => initialized_report) ; 

Close the report's input file: 

(from Inventory_Reports body) 

152 Record_AM. Ops. Close ( 

153 opened_dev => opened_local_parts_f ile) ; 



155 end Print_report_by_part; 

V-2.2.9 Printing a Report from a Sorted File 
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Calls Used: 

Byte_Stream_AM . Open_by_name 

Opens the report output device. 

Directory_Mgt . Retrieve 

Retrieves the report definition, given the report's pathname. 

Event_Mgt . Wait_f or_all 

Waits for all of a specified set of events to occur. 

Pipe_Mgt . Convert_j>ipe_to_device 

Converts a pipe AD into a device AD. 

Pipe_Mgt . Create_pipe 

Creates a new pipe. 

Process_Mgt .Deallocate 

Deallocates a spawned process. 

Process_Mgt . Get_process_globals_entry 

Gets one of the process globals entries (in this case, this process's AD). 

Process_Mgt . Spawn_jprocess 

Creates a new process which runs concurrently with the calling process. A 
termination action is specified. 

Record_AM. Ops . Open 

Given a device AD, opens a file or device for record access. 

Record_AM . Open_by_name 

Given a pathname, opens a file or device for record access. 

Record_AM. Ops . Get_DDef 

Gets the DDef imderlying an opened device. 

Record_AM. Ops. Close 

Qoses a file. 

Report_Handler . Initialize 

Initializes an opened report, given the report DDef and the input and out- 
put devices. 

Report_Handler .Print 

Prints an initialized report. 

Sort_Merge_Interf ace . Sort 

Sorts records from an input device to an output device, using a sort DDef 
to specify the sort fields and their ordering. 



This section describes how to sort a file and use the sorted records as input to a report. The 
example uses a pipe from the sort procedure to the report procedure. 

Create a Report Definition 

Create and store the report's DDef, as described in the previous section, "Creating a Simple 
Report". 

Create a Sort Definition 

Create the sort DDef, which defines the sort key fields and their ordering. This can be done 
interactively, with the TBD utility, or procedurally, using calls to Data_Def inition_Mgt. 
Store the sort DDef under a pathname. 
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Your Sort Procedure 

Implement the file-sorting procedure: 

• Use the subprogram_value pragma to get an AD to your "Sort" procedure (process): 

(from Invent ory_Reports body) 
42 type connect ion_recorci is 

4 6 record 

47 sort_out: Device_Defs.opened_device; 

48 — Output from "Sort" to pipe. 

49 report_in: Device_Defs .opened_device; 

50 — Input from pipe to "Print". 

51 report_out: Device_Defs.openeddevice; 

52 — Output device for "Print" . 

53 end record; 

158 procedure Sort ( 

159 param_buffer : System. address; 

161 param_length : System. ordinal) 

168 is 

169 

170 conn_rec: connection_record; 

172 FOR conn_rec USE AT param_buff er; 

187* * begin 

231 end Sort; 

232 pragma subprogram_value ( 

233 Process_Mgt . Initial_proc, 

234 Sort); 

• Open the input file, with Record_AM . Ops . Open or 
Record_AM . Ops . Open_by_name. 

• Get the sort DDef: 

(from Inventory_Reports body) 

182 opened_sort_DDef : 

183 Device_Defs.opened_device; 

184 sort_DDef_reference: 

185 Data_Definition_Mgt .node_reference; 

200 opened_sort_DDef := Record_AM.Open_by_name ( 

201 name => 

202 sort_by_loc_DDef_pathname, 

203 input_output => Device_Defs. input, 

204 allow => Device_Defs. readers, 

205 block => true) ; 

209 sort_DDef_reference := 

210 Record_AM.Ops.Get_DDef ( 

211 opened_dev => opened_sort_DDef ) ; 

• Use the input end of the pipe for the output device. 

• CaU Sort_Merge_Interf ace . Sort with the sort DDef, and the opened input and 
output devices. 
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(from Inventory_Reports body) 

217 Sort_Merge_Interf ace. Sort ( 

218 input_device => 

219 opened_local_parts_file, 

220 DDef => sort_DDef_reference, 

221 output_device => conn_rec. sort_out, 

222 stable_sort => true, 

223 tuning_opts => 

224 Sort_Merge_Interface.no_tuning) ; 

• Close the input file, with Recor d_AM . Ops . Clo se. 
Your Report Procedure 

Implement the report procedure: 

• Use the subprogram_value pragma to get an AD to your "Print" procedure (process). 

• Get the report DDef: 

(from Invent ory_Reports body) 
252 report_DDef: Data_Def inition_Mgt .DDef_AD; 

266 report_DDef := Dbef_from_untyped ( 

267 Directory_Mgt .Retrieve ( 

268 report_by_loc_DDef_pathname) ) ; 

• Use the output end of the pipe for the report input device. 

• Call Report_Handler . Initialize with the report DDef, and the opened report in- 
put and output devices. 

• Call Report_Handler . Print to print the report. 

• Close the report output device, by calling Record_AM . Ops . Close. 

Creating a Pipe 

Create the pipe, and open its input and output ends: 

(from Inventory_Reports body) 
308 sort_pipe: Pipe_Mgt .pipe_AD; 
334 sort_pipe := Pipe_Mgt .Great e_pipe; 

340 sort_out => Record_AM. Ops. Open ( 

34 1 Pipe_Mgt . Convert_pipe_to_device ( 

342 sort_pipe) , 

343 Device_De fs. output ) , 

344 report_in => Record_AM.Ops.Open ( 
34 5 Pipe_Mgt . Convert_pipe_to_device ( 
34 6 sort_pipe) , 

34 7 Device_Defs. input) , 

Spawning Your Sort and Print Processes 

Spawn your "Sort" and "Print" processes: 
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(from Inventory_Reports body) 

311 this_process_un typed: System. untyped_word; 

316 sort_process: Process_Mgt_Types.process_AD; 

319 print_process : Process_Mgt_Types.process_AD; 

354 this_process_untyped := 

355 Process_Mgt .Get_process_globals_entry { 

356 Process_Mgt_Types. process) ; 

360 sort_process := Process_Mgt .Spawn_j3rocess ( 

361 init_proc => Sort' subprogram_value, 

362 param_buffer => conn_rec' address, 

363 term_action => ( 

364 event => Event_Mgt .user_l(, 

365 message => System. null_address, 

366 destination => this_process_untyped) ) ; 

370 print_process := Process_Mgt .Spawn_process { 

371 init_proc => Print' subprogram_value, 

372 param_buffer => conn_rec' address, 

373 term_action => ( 

374 event => Event_Mgt .user_2, 

375 message => System. null_address, 

376 destination => this_process_untyped) ) ; 

Wait for completion of the two processes, then deallocate them: 

(from Inventory_Reports body) 

322 term_events: Event_Mgt .action_record_list (2) ; 

380 Event_Mgt .Wait_f or_all ( 

381 events => 

382 (Event_Mgt.user_l .. Event_Mgt . user_2 => 

383 true, 

384 others => false) , 

385 action_list => term_events) ; 

390 Process_Mgt .Deallocate (sort_process) ; 

391 Process_Mgt .Deallocate (print process); 
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A BiiN program can be controlled by menus or commands. 

A data file's record layout can be used to generate default form and report formats. Form 
and report formats can be updated without changing the calling program. 

Input to a program can come from a window, a file, or a data entry form. 

Output fi'om a program can be displayed in a form, written to a device, or printed as a 
report. 
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This chapter describes how to process a program's invocation and runtime commands and 
arguments. 

Packages Used: 

CL_D e f s Contains declarations used by the command service, for processing com- 

mand language (CL) arguments and variables. 

Command_Handler 

Contains operations for reading and processing program commands and 
arguments. 

Corranand_Execution 

Contains a procedural interface to command execution. 



New commands for command-driven programs are created with the manage . commands 
command set in the manage . program utility. Your program calls the command service 
(with the command definition) to get and parse each command. Your program can then per- 
form (implement) the returned command. 

There are three ways in which you can create the command definitions for a program's com- 
mands: 

1. Enter manage . commands runtime commands to create the command definitions 
(command DDefs) interactively. 

2. Create manage . commands runtime commands in a command file. Submit the command 
file to the manage . program utility to create the command DDefs. 

3. Include manage . commands runtime commands as tagged comment lines in a program's 
source file. Use the : tagged_commands argument to the manage . program utility to 
extract and process the definition commands from the tagged comment lines. 

The invocation command DDef is stored with the program itself. Runtime commands sets are 
stored under pathnames, which your program then uses when opening command set process- 
ing. 



V-3.1 Concepts 



New commands are defined using the manage . commands command set in the 
manage . program utility - see the B«W™ Command and Message Guide. 

The command service uses the command definitions - to help the user correctly enter and 
complete a command. 

There are three types of commands processed by the command service - built-in commands, 
CLEX commands, and program-defined commands; see "Types of Commands", below. 

built-in commands Part of, and processed by, the command service itself. Built-in runtime 
commands direcdy perform some action, such as setting a variable 
(set . variable). Built-in control commands control the logical 
flow of commands (if / then / else / endif). 

CLEX commands Commands specific to the command language executive (CLEX). 

program-defined commands 

Each program has an invocation command, which is entered to CLEX 
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to invoke (execute) the program. Programs using the command service 
define their own runtime commands, which control and are im- 
plemented by the program. 

Commands can be read from many different devices - including terminals, pipes, and files. 

Commands are entered and confirmed without program intervention - a complete, correct 
command is then available to the program. 

"help" is available to the user for each command and each argument - the command ser- 
vice displays requested "help" texts (defined with the command DDef), without requiring 
any program action. 

A command consists of up to three parts: 

command. name [ :argument=value] . . . 

[ : :control_option=value] . . . 

command . name The name of the command. The command name may have two parts, 
separated by a period: command_verb . command_noun. See 
"Command Names", below. 

.•argument = value 

Zero, one, or more arguments may be part of a command. See 
"Argument Types and Values", below. 

- Arguments have a name, a type, and a value - an argument name is 
a string of characters, preceded by a colon (**:", for example, 

: argument_name). The argument is one of seven types: 
boolean, integer, range, string, string list, pointer, or "derived" 
(actual value may be any of the preceding six types). The argument 
value's type must match the defined argument type. 

- Arguments may be mandatory or optional - mandatory arguments 
must be entered with the command name; there is no default. Op- 
tional argimients may be entered to specify an argument value other 
than the default. 

- An optional argument's value may be entered or defaulted - if an 
explicit value ( : argument =value) is not entered, the argument 
has its default value, if any, defined with the command. 

: :control_option = value 

There are several control options defined in the command language, 
used to request input/output redirection, background execution, and so 
on. See "Control Options", below. 

Control options are processed by the command service. Control op- 
tions entered with a command remain in effect until the next command 
is read (next Command_Handler . Get_command call). 

An optional command history can be used - to record commands entered. 

- The last cli . num_last_cmds commands entered are stored in a command buffer in 
active space. 

- Commands may be re-executed from the command buffer, either by index number, or 
by giving an unambiguous abbreviation (or a pattern to be matched) of a previous com- 
mand. 

- The command history can be turned on and off as desired. 
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A command file is a sequence of commands stored in a text file - command files can be 
included into the command input stream by using the built-in include . command com- 
mand. A command file can be made into an executable script by using the make . s cr ipt 
utility. 

There are two methods for reading commands from an arbitrary file or device: 

- Call Command_Handler . Open_runtime_command_j5rocessing on the file 
or device to return an opened command input device. Use 
Command_Handler . Get__ calls with that command input device. 

- Enter the built-in runtime command include . command, specifying the file's or 
device's pathname. The specified file's or device's records are inserted into the com- 
mand input stream. When the end of the file or device is reached, command input 
returns to the original device. The program reads the included commands as part of 
the original device's input command sequence. 

The record access method is supported for runtime command input - the command 
service's implementation of Record_AM allows non-Ada languages to read and process 
runtime commands. See the package description for Command_Handler, in the 
BUN™ /OS Reference Manual. 

There is support for BiiN™/UX invocation command conventions - for such constructions as 
Is -Id. The command service can set the expected invocation command variables (argv, 
argc, envp); see the BiiN^lUX Commands Reference Manual. 

V-3.1.1 Developing Command-Driven Programs 

This section describes how to develop a command-driven program. 

Not all programs are suitable for command-oriented input Some applications can use menu- 
oriented input (see Qiapter V-5). 

Most programs using the command service will be new utilities. 

Determine the invocation command name and the arguments your program will use on entry. 
Create and store its command definition, as described above and in Section V-3.2.1, "Defining 
an Invocation Command", below. 

To develop the runtime commands for your program: 

• Each distinct function that the program performs should have its own command. Com- 
mands are defined during program development 



• 



• 



Group related commands into command sets. Separate command sets may be defined for 
different program tasks or for different user groups. 



• Create and store the command definition(s) as described above and in Section V-3.2.2, 
"Defining a Runtime Command Set", below. 



V-3.1 .2 Types of Commands 



There are three types of commands processed by the command service: built-in commands, 
CLEX commands, and program-defined commands. All of these commands use the CL syntax. 

built-in commands Commands which are built into, and processed by, the command service. 
CLEX commands Commands which are recognized and processed by CLEX. 
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program-defined commands 

Commands which are specific to a program: 

invocation command 

The command which is entered to CLEX to execute 
the program. 

runtime commands Commands entered to and processed by your program. 

Runtime commands may be placed in a startup com- 
mand file, to be automatically processed by your 
program directly after invocation, if desired. 

Each of these three types of commands are described in the conesponding sections below. 

V-3.1.2.1 Built-in Commands 

Some commands are built into and processed by the command service. These commands can 
be entered to CLEX, and are part of all command sets (see "Program-Defined Commands", 
below). 

There are two types of built-in commands, built-in control commands and built-in runtime 
commands. Each of these two types is described in the following tables. 

Table V-3-1 describes the built-in control commands. 

Table V-3-1. Built-in Control Commands 



Control Commands 


Description 


label label juxme 


Labels a point in the conunand input stream; used by got o. The 
label jtame may be any sequence of alphanumeric characters. 


goto label 


Transfers command input to the first command following the given 
label 


if condition then 
commands 

elsif condition 
commands 

else 

commands 

endif 


Performs commands (any type), da)ending on the current evalua- 
tion of condition. A condition can be any Doolean expression, for 
example, ($i < 5) OR $$exists (~/log/log_file) . 


loop 

commands 
[if condition then 
[commands] 

exitloop 
endif] 

[commands] 

endloop 


Executes commands rq>eatedly, until an exitloop is executed, 
or forever. 


for range expression loop 
commands 

[exitloop] 
endloop 


Repeatedly executes the loop, once for each element in the range 
expression. The ron^eexpre^^ion may be either a range (for $i 
in -3. .5), orastnnghst(for $i in (abed e)). An 
exitloop condition may be specified. 


while condition loop 
commands 

[exitloop] 
endloop 


While condition evaluates true, executes the loop. An exitloop 
may be specified. 



Table V-3-2 describes the built-in runtime commands. 

Built-in runtime commands may have appropriate control options, for example: 

eclio Hello ::output=x 
echo Hello > x 
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Table ¥-3-2. Built-in Runtime Commands 



Commands 


Description 


echo 


Echoes a given value to the standard ou^ut Useful for displaying 
infonnation while in a command loop. 


run 


Executes a program or script. 


set . cur rent_di rectory 


Sets the current directory to the given pathname. 


list . current_di rectory 


Lists the current directory's pathname. 


set. alias 


Defmes an alias name for a given string. 


remove. alias 


Removes oaa or more alias names. 


list. alias 


Lists the current values of the given alias names. 


include . command 


Insens the given file into the runtime command input. Usdful for 
reading pre-defined command sequences stored in files. 


set . command_path 


Sets the current command path (command name space) to the 
givai set f string list) of diiectorv pathnames. With no argument 
value, updates me s^ of available commands, by searching 
through the current conunand name space, in order (of directories 
currently specified). 


list . commandjpath 


Lists the current pathnames in the conmiand path. 


list.last_commands 


Lists the last commands bt^er, out of which commands can be 
re-executed with redo . last_commands. 


redo . last_commands 


Repeats a previous command, or a sequence of commands. 


set. history _log 


Sets the scope (local or global) of history recordine for subsequent 
jobs. If local (default), invoked jobs will not inherit the caller's 
nistory file. If global, invdced jobs do inherit the caller's 
history file. 


start. history _log 


Creates a user history file to be the current history, or restarts 
recordii^ into the job histoiy file after stop . hi story log was 
called, u the user nistory file name is not specified, the default 
pathname is ~/$logon.history_dir/history/i/n«yraOTp' 


stop.history_log 


St^s recording into the job histoiy file, and into the c<»nmand 


list. history _log 


Lists entries from the job histoiy file, or f nnn a specified history 
file. 


create . variable 


Creates a new CL variable in memoiy. 


set. variable 


Assigns a value to a CL variable. 


remove. variable 


Removes a CL variable from memoiy. 


list. variable 


Lists the names, types, modes, and values of the given variaUes. 



V-3.1.2.2 CLEX Commands 

Some commands are defined by the Command Language Executive (CLEX) for various 
system-related functions. See the BiiN^ Command Language Executive Guide for a complete 
description. 

Programs and utilities are called from CLEX; each has its own invocation command. 

V-3.1.2.3 Program-Defined Commands 

There arc two types of program-defined commands: the program's invocation command, en- 
tered to CLEX to invoke your program, and the program's runtime commands, which are 
processed by and control the program. 
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All programs (except ported C programs) should define their invocation commands. The in- 
vocation command definition contains the name of your program and defines any arguments. 

Programs using the command service have runtime commands, grouped in command sets. 

• A command set defines the names of all commands and their argument names, types, 
defaults, and permissible values. Command sets are defined during program development, 
using the manage . program utility. 

• All command sets include all the built-in commands. See "Entering Commands to 
Programs", below. 

• All command sets should have an abort or exit command defined, to stop command 
processing and terminate the program. These commands are not built in, but should be 
defined with each command set. 

• The command set definition is a command DDef, stored under a pathname. The 
Command_Handler . Open_ and Command_Handler . Change_cmd_set calls have 
a mandatory parameter for the pathname of the command set definition. 

• There may be several command sets defined for one program; for example, one primary 
command set for general operations, some of which in turn have their own command sets. 
The current command set may be changed with 

Command_Handler . Change_cmd_set. 

• Command_Handler calls use the command set definition to automatically check for cor- 
rect command names, ensure completion of mandatory arguments, and supply default 
values for optional arguments. 

All commands, except the invocation command itself, musthawc a command definition. If 
there is no invocation command definition, calls in this package will succeed if the invocation 
command uses CLEX syntax. No type checking, range checking, or consistency checking can 
be performed on the entered arguments (see below, "Reading the Invocation Command", in 
Techniques). 

V-3.1.3 Review of Command Syntax 

This section briefly reviews the three components of a command: 

• command name 

• command arguments, if any 

• control options, if any 

V-3.1.3.1 Command Name 

The command name may be one word (for example, echo) or have two parts, separated by a 
period (**."; for example, set . alias). The two parts of a command name are the verb (for 
example, set .) and ttie noun (for example, alias). 

For invocation commands (see "Types of Commands", above), the command name may be 
preceded by the absolute or relative pathname of the directory where the named program or 
script resides: ~/ library/ command . name 

There are some command verbs suggested for compatibility with the OS utilities: 
change For "update", "modify". 
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list 
remove 



For "show", "display". 
For "delete". "kiU". 



V-3.U.2 Argument Types and Values 

Argument types and values are briefly described. 

Argument Types 

Table V-3-3 describes each of the seven argument types. 

An argument's default value may be a constant or a variable. In an argument's definition, any 
command language ((X) variable (of the correct type) can be used as the default value of an 
argument. 

Table V-3-3. Argument Types 



Argument Types 


Description 


boolean 


Possible values are true or false. Boolean arguments normally 
have their defined default value f al se. Entering a boolean ar- 
gument without a value is recognized as true. For example, 

: boolean argument is the same as : boolean argument 
= true. 


integer 


A sequoice of numbers, possibly including underscores (" "), and 
optionally preceded by a plus C'+") or minus ("-") sign- Possible 
values are m the range - 2 '^ 31 (-2 147 483 648)to 2'^32-l 
(4_294_967_295). _ - _ 


range 


Two integers, separated by two periods ("..'*), for example, 
-5 . . 3. Either or both of the low and high values may be 
defaulted. 


string 


Any sequence of characters, possibly enclosed in double quotation 
manes 0* " ".forexample, "string of characters"). 


string list 


One or more strings, enclosed in parentheses " ", sq>arated by 
spaces; for example, ("string value 1" string2 
"string value 3"). Thete&nseverai.typ&s (lexical classes) 
of strings, such as blankless and symbolic (for pathnames); 

see the BiiN^ Command and Message Guide. 


pointer 


A relative or absolute pathname to a stored object; for example, 

-/object. 


derived 


Any of the above six types. The actual type of a derived 
variable type is determined (derived) by the command service from 
the format of the entered value. 
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Argument Values 

An argument value can be entered with or without the argument name, that is, in named or 
positional notation. 

named notation The argument name is followed by an equals sign (* *=") and the argument 
value. Boolean arguments are a special case; entering the name of a 
boolean argument without a value ( : boolean_ar g) is the same as enter- 
ing :boolean_arg == true. 

For example: 

:boolean_argument 

(or) 
:boolean_argument = true 

: integer_argument = 15 

positional notation Argument values entered by themselves are assigned to arguments in se- 
quence (the sequence of argimients in the command definition). That is, 
the first unentered argument (one which does not already have a value 
entered in named notation) is assigned the entered value. 

Building New Commands 



For example, the first argument of the built-in command 
set . current_directory is the directory name ( : directory). 
Entering set . current_directory ~/my_dir is equivalent to 
entering set . current_directory : directory = ~/my_dir 

Named and positional notation can both be used in a single command, if you are sure of the 
defined order of arguments. 

An argument's value may be entered as a constant, variable, function, or expression: 

constant A simple value of the argument's type. For example, 

: range_arg = 4 . . 7 

variable A variable name, of the same type as the argument, whose value is as- 

signed to the argument For example, 

: string_arg = $user . name 
function A CL function giving a value of the argument's type. For example, 

:integer_arg == $$len ($string_var) 
expression A CL expression giving a value of the argument's type. For example, 

:boolean_arg = (not $boolean_var) 



V-3.1.3.3 Control Options 



Several control options are part of the command language. A control option is specified by a 
double colon (** : : "), the control option's name (one of the names defined below), and pos- 
sibly a value: 

: :control_option = value 

The command service processes all control options. The given control options are set for the 
current command and remain in effect until the next Command_Handler . Get_command 
caU. 

Control options for CLEX commands are processed by CLEX. 

Control options for invocation commands (see "Program-Defined Commands", above) are also 
processed by CLEX, and are not directly available to the called program or script. 

Table V-3-4 describes each of the control options currently defined. 
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Table V-3-4. Control Options for Runtime Commands 



Control Options 


Description 


: : input or < 


Specifies an input device's (or ffle's) pathname, redirecting the 
standard input device. 


: : output or > 


Specifies an output device's (or file's) pathname, redirecting the 
standard output device. 


: : output_extend or >> 


Whether to extend (if true) or ovarwrite (if false) the ou^t device. 
Default is to overwrite. 


: : message 


Specifies a message device's (or file's) pathname, redireaing the 
standard message device. 


: :message_extend 


Whether to extoid (if true) or overwrite (if false) the message 
device. Default is to overwrite. 


: : window 


Requests that the command be executed in a separate window. 


: : service 


Determines the scheduling service object (SSO) to be used for this 
command. 


: : node 


Determines the node on which the command is to be run, for 
example, : :node=///my_node. 


: :history_log 


Starts a new history log file for this command, for example, 

: :history_log = ~/log/this_log. 


: : debug 


Specifies that this command is to be run in debug mode (see the 
Bit/V™ Application Debugger Guide. 


: : separate or & 


Requests that this command be executed as a separate job. 



V-3.1 .4 Review of Command Definitions 

The following is a short example of the command definition syntax (that is, the runtime com- 
mands for the manage . program utility). See the BiiN^ Command and Message Guide for 
comfdete information. 

All commands are part of a given command DDef. There will be one command DDef for the 
invocation command, and one for each command set 

An invocation command is defined as follows: 

set. program ~/ example/my _program 

— The invocation name is the same as the program's name 

manage . commands — call the "manage. commands" command set 

create . lnvocation_command 

define. argument :arg_name = my_argument_l \ 
:type = string 
set .mandatory 
end 

define. argument :arg_name = my_argument_2 \ 
:type = boolean 
set .mandatory 
end 

end 

exit — exit "manage. commands" 
exit — exit "manage .program" 

Runtime commands are defined in sets: 

create. runt ime_command_set :cmd_def = ~/example/my_program.command_set 

define. command :cmd_name = command. name_l 

define. argument : arg name = command argument 1 \ 
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•type = range 
set .mandatory 
end 
end 

define. command :cmd_name = comma nd.name_2 

define. argument :arg_name = command_argument_l \ 

:type = boolean 
end 

define. argument :arg_name = command_argument_2 \ 

:type = range 
end 
end 

define. command :cmd_name = exit 
end 
end 

After creating a command DDef, it can be listed with the list : cmd_def nmtime com- 
mand. 

Help Texts 

Help texts are defined with each command and argument. Help texts are stored in help files. 
The default help file is part of a program's OEO. 

Either use the default help file associated with a program, or set the help file to be used with 
set . help_f ile message _filej?athname. 

Before the end of each defined command and argument, enter the help text, using the 
set . description command: 

create. runt ime_command_set :cmd_def = ~/example/my_program.command_set 

define . command : cmd_name = command . name 

define. argument :arg_name = command_argument \ 

:type = range 

set .mandatory 

set .description :text = " 

Range of values for this command. 
II 

end 

set .description :text = " 

Performs a given action, using the 

values specified with ' : command_argument ' . 
II 

end 

define. command :cmd_name = exit 

set .description :text = " 

Exits the program. 
II 

end 
end 

V-3.1.5 Types of Command Input 

Any device supporting the byte stream access method can be used for command input. 
The usual interactive command input device is the standard input 
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After Command_Handler . Get_coiranand has been called to parse a new command (and 
return the command name and command index), the command may be read in several ways: 

• In parts, reading each argument, with a series Conimand_Handler . Get_argwnentjype 
calls. See the appropriate sections under Techniques, below. 

• As a string, using Coiranand_Handler . Get_coininand_string. 

• As a record, using Recor d_AM . Ops . Read. See the package description for 
Coiranand__Handler, in the BiiN^IOS Reference Manual 

Startup Command File 

Runtime commands can be stored in a particular startup file, to be read automatically by 
your program. After the startup file has been read, runtime commands may be entered. 

CaU Coinmand_Handler . Open_startup_command_processing to access the star- 
tup command file, then call Coiranand_Handler . Get_coiranand to get each command. 

Process each command as a runtime command (see "Reading Runtime Commands", below). 

When the last command (for example, exit) is read, or the end of the startup file is reached, 
close the startup command input device by calling Coiranand_Handler . Close. 

Changing the Command Set 

The Command_Handler . Change_cmd_set procedure changes the current command set 
definition. 

Reading Commands as Records 

The command service supports the record access method for command input. Programs writ- 
ten in non-Ada languages can use the record access method (Record_AM . Ops . Read call) 
to get a record of the current command. 

See the package description for Coinmand_Handler, in the BiiN^IOS Reference Manual. 

V-3.1 .6 Alternatives to Command Input 

There are several altematives to using commands to control your program: 

menus Read menu item selections. See Chapter V-5, Programming with Menus. 

keyboard input Read the keyboard directly. See Chapter IV-5, Using Character Display 
110. 

V-3.1 .7 Entering Commands to Programs 

AU command sets include all of the built-in commands. The user can enter these commands as 
desired; the command service processes these commands transparently to your program. 

Some usefiil built-in commands are: 

run Executes any invocation command, for another program or script. For 

example, to display the current directory's entries, the user would enter 

run "list . current_directory". 
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include . command 

Includes a given command file into the command input stream. At the end 
of the file, command input returns to the default 

. alias The three . alias commands (set . alias, list . alias, 

remove . alias) can set up aliases inside your program, for your runtime 
commands. 

. variable The four . variable commands (create . variable, 

set . variable, list . variable, remove . variable) can create 
and set variables for your program to read, or for use as argument values. 

control The control commands (if / then / else / endif, andthe 

loop / exitloop / endloop constructs) can set up runtime com- 
mand loops, possibly using variables. 



V-3.2 Techniques 

After reading this section, you will be able to: 

• Define an invocation command 

• Define runtime commands 

• Create and store invocation and runtime commands 

• Read the invocation command 

• Read argument values 

• Read a runtime command 

• Read a command input line as entered 

• Give a command to be executed by CLEX. 

V-3.2.1 Defining an Invocation Command 

utility Used: 

manage .program 

Creates invocation command and runtime command set DDefs. 



To define an invocation command: 

1 . Determine the invocation name of your program, and use that entry name for your ex- 
ecutable program object 

2. Determine the arguments for the invocation command, their types and defaults, and 
whether each argument is mandatory or optional. 

3. Create an invocation command definition, in one of two ways: 

• In your program source text, using tagged comment lines. Use the 

: tagged_commands argument to the manage . program utility to extract the com- 
mand definition into a command file. 

• In a separate command file. 
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4. Use the manage . program utility, optionally with a file of definition commands as input, 
to create and store the invocation command's DDef. 

V-3.2.2 Defining a Runtime Command Set 

utility Used: 

manage .program 

Creates invocation command and runtime command set DDefs. 



Determine the names and arguments for each runtime command. 

Follow the process described above, in "Defining an Invocation Command", to create the com- 
mand set DDef(s). 

V-3.2.3 Reading the Invocation Command 

Calls Used: 

Command_Handler . Open_invocation_command__processing 
Opens a device for reading the invocation conmiand. 



To read the invocation command, just call 

Command_Handler . Open_invocation_command_processing; there is only one 

command, and it is already parsed. 

Next, read each argument value, as described below ("Processing Command Arguments"). 

V-3.2.4 Processing Command Arguments 
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Calls Used: 

Coiranand_Hanciler . Get_argument_type 

Gets the value of a given argument of the current command. 

Command_Handler . Get_boolean 

Conimand_Handler . Get_integer 

Coiranand_Handler . Get_range 

Command_Handler . Get_pointer 

Coinmand_Handler . Get_string 

Coinmand_Handler . Get_enumeration_index 

Coinmand_Handler . Get_string_list 

Coiranand_Handler . Get_number_of_string_list_elements 

Coinmand_Handler . Get_string_list_element 

Conimand_Handler . Get_argument_inf o 

Gets a record containing the name of an argument and the type and origin 
of its value. The origin of the argument's value is none, entered by the 
user, defined default value or defined default variable's value. This infor- 
mation is usually only relevant for derived argument types or if multiple 
default value sources are supported. 



To read argument values, you must have an opened command input device and a current 
command. The current command is either the invocation command or has been gotten by 

Command_Handler . Get_command. 

You must know at least the position (or name) of the argument: 

argument name Defined by the command definition. 

For positional notation without a command definition (invocation com- 
mands only), the argument names default to pi, p2, p3 and so forth, 
where n in pn is the argument position (argument number) in the com- 
mand. 

The name pO is reserved for the command name. Its argument number is 
zero. The name cmd_name is also predefined for the invocation 
command's name. 

argument number Defined by the command definition, or else by the position in the invoca- 
tion command line. 

Argument number zero is the command name itself. 

You may specify either the argument name or number in a 

Command_Handler . Get_argument_type call. For ease of program maintenance, using ar- 
gument numbers is recommended (in case the names change). 

• If both a name and a number are specified, the name is ignored. 

• If no number is specified, the given name is used. 

• If neither the argument name nor the argument number are specified, the call raises 

System_Exceptions .bad_j3arameter. 
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Call Coiranand_Handler . Get_argument_inf o if necessary (always necessary for 
derived argument types) for the type of the argument and the origin of its current value. 

Use the appropriate Cormnand_Handler . Get_argwnent_type call to return the value of 
each argument 

If no value has been entered for an argument, and no default value is defined, 
CL_Def s . no_value is raised. This is only possible for arguments defined as "not 
mandatory", since the command service guarantees that all mandatory arguments have a value. 

V-3.2.5 Processing Runtime Commands 

Calls Used: 

Coinmand_Handler . Get_coinmand 

Gets and parses the next command from a given input device. 

Command_Handler . Get_argument_type 

Gets the value of an argument of the current command. 



The most common way to read runtime commands is to open the runtime command input 
device, then use a loop to read and process runtime commands until an exit (or similar) 
command is entered. 

V-3.2.6 Reading a Command Input Line as Text 

Calls Used: 

Conimand_Handler . Get_line 

Gets a line of text from a given input device. 



Reads a line of text, terminated by a carriage retumAinefeed, directly from the command input 
device. This procedure can be used to read lines of data fix)m the command input device, 
bypassing the command service's parsing mechanism. 

An optional prompt can be specified, to alert the interactive user that the entered line will not 
be processed as a command. 

V-3.2.7 Executing Commands from a Program 

Calls Used: 

Coniinand_Execution . Execute_coniinand 

Executes one or more CLEX commands. Blocks until finished. 

Conimand_Execution . Run_program_or_script 

Executes one CLEX invocation command, in a separate job. 



Set up a text record of the desired command(s), and make the appropriate call. 
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V-3.3 Summary 

TM 

• Commands provide a consistent user control mechanism, used by all BiiN utilities. 

• A command consists of the command name, arguments if any, and possibly some control 
options. 

• The command service requires the user to enter a complete command; help is available for 
each command and for each argument. 

• Commands can be read from any device supporting the byte stream access method, includ- 
ing files and pipes. 

• Some commands are built-in; other commands are defined by programs using the command 
service (including CLEX itself). 

• Built-in commands are part of every command set. These commands are intercepted and 
processed by the command service itself. 

• New commands arc defined with the manage . commands command set in the 
manage . program utility. Command DDefs are stored under a pathname. 

• New commands are processed by the command service, using a command DDef. The 
parsed command can be read in parts, or as a string, using calls in the 
Command_Handler package. A command can be read as a record using the 
Record_AM . Ops . Read call. 

• Your program can request execution of a CLEX command, optionally in a new CLEX 
instance, using calls in the Command_Execution package. 

• Menus are another method for the user to control a program. See Chapter V-5, 
Programming with Menus. 
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This chapter describes how to create, read, set, and remove command language (CL) variables, 
using calls in the Environment_Mgt package. Some CL variables influence the 
application's environment; for example, the cli . prompt variable contains CLEX's prompt 
string. CL variables can also be used to save information and share it with subsequent jobs. 

Packages Used: 

CL_Def s Contains declarations used by the command service, for processing com- 

mand language (CL) arguments and variables. 

Environment_Mgt 

Contains operations to get, set, or remove local and global environment 
variables. 



Figure V-4-1 shows how variables in passive store and active memory arc related, and the 
order of evaluation for variables. 



Passive Store (manage. var_groups utility) 



System Variable Groups (/var_groups) 



User Variable Groups (~/var_groups) 



evaluation 



copied on 
reference 
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Figure V-4-1. Command Language Variables 



This chapter discusses the use and modification of variables, using calls in the 
Environment_Mgt package. For example: 

• How to read a variable's value. 

• How to set a variable's value. Variables are created when set, if they do not already exist. 

• How to overwrite an existing variable's value. 

• How to remove a variable. 



V-4-2 
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V-4.1 Concepts 

These concepts must be understood to use CL variables: 

• A variable has a name, a type, a mode, and a value - 

name A Q- string of letters and digits, up to CL_De f s . max_name_s z 

characters. 

type One of the CL_Def s types: boolean, integer, range, string, 

string list, or pointer. 

mode Either CL_Def s . read_only, indicating that the variable can be 

read but not assigned, or CL_Def s . read_write, indicating that the 
variable can be read or assigned a value. 

value Any value of the appropriate type. 

• There are two types of variables - those dynamically created in active memory, using calls 
in Environment_Mgt (and the . variable commands built into the command service) 
and those defined in passive store, using the manage . var iable_groups utility. 

• Dynamically created variables exist in one of two buffers - either a local buffer or the 
global buffer. The local buffer exists for the duration of the job; the global buffer exists for 
the duration of the session. All processes in a job share the same variables (buffers). 

• Variables in passive store are stored in system and user groups - system variable groups 
can only be updated by the system administrator. User variable groups are maintained with 
the manage . variable_groups utility. 

- Sets of system or user variables - may be collected together in groups, by giving them a 
group name. For example, cli . prompt is the prompt variable in the cli . group. 
Group variables may only be created with the manage . variable_groups utility. 

- System variable groups apply to all sessions on this node. System variables are created 
and maintained by the system administrator. System variables are in pre-defined 
groups, stored in the system directory / var_groups. See the "System Variables" 
section below. 

- User variable groups contain user-specific information, values, and defaults. User vari- 
ables are created and maintained with the manage . variable_groups utility. User 
variables are stored in a "var_groups" directory in your home directory 

(~/var_groups). 

- Job variables are created and used by jobs, in the global buffer. Job variables may be 
created and used either by calls to Environment_Mgt or by programs using the 
Command_Handler package (programs with runtime commands). Subsequent jobs 
in this session inherit all existing job variables. 

- Local variables are used like job variables, but only exist for the duration of a job. 
Local variables are stored in the local buffer. 

• Variable names are evaluated upwards until found - 

1. local buffer 

2. global buffer 

3. user variable groups (~ /var_groups directory) 

4. system variable groups (/var_groups directory) 
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• Each job has its own copy of system, user, and job variables (global buffer), and local 
variables (local buffer) - referencing a user or system variable causes a copy of that vari- 
able to be created in the job's global variable buffer. Job variables may be created in either 
the global or local buffer. Local variables are created, set, and removed in the job's local 
variable buffer. 

• Subsequent jobs are affected by changes to the global buffer - since they inherit a copy of 
the current global buffer. 

• Changes only affect the job's copy of the variables - changes to stored (system or user) 
variables are actually made in the job's global variable buffer. Use the 

manage . variable_groups utility to change system and user variables permanently. 

• Variables may also be created and changed - using four commands built into the command 
service: 

create . variable 

Creates a new local or global variable, optionally with an initial value. 

set . variable Sets a value into a variable which has mode CL_Def s . read_write. 

remove . variable 

Removes a variable from the local or global buffer. The version of the 
variable in passive store is not affected. 

list . variable Lists the type, mode, name, and current value of the specified variables. 

• "read_write" system and user variables can be hidden - by creating a new variable with 
the same name in either of the job's buffers, "r ead_only" system or user variables 
cannot be hidden this way. 

• Rights for Environment_Mgt calls - you must have use rights to read, modify rights to 
set, and control rights to create or remove variables. Group variables, being stored under 
pathnames, are subject to the usual access right restrictions. 

• All pre-defined variables - are either part of a variable group, or are dynamically created 
(OEO and status). 

status integer variable created by each CLEX, before executing its first 

command. This variable is in the calling job's local buffer, and is set 
by CLEX from the exit status of the last executed command. 

The command service's built-in run command also creates a local 
status variable. The value of this variable is the exit status of the 
run program or script. 

OEO pointer variable created by the command service for every program. 

This variable is a pointer to the program's outside environment object 
(OEO), or null if there is no OEO. 

OEO is needed for the command service's implementation of 
Record_AM; see the Command_Handler package for more infor- 
mation. 

V-4.1.1 System Variables 

System variables are defined as part of CLEX. Current system variables are in six groups: 

• logon 

• cli (command line interface) 
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• pglob (process globals) 

• user 

• msg (message) 

• ux(BiiN™AJX) 

V-4.2 Techniques 

After reading this section, you will be able to: 

• Get a variable's type (boolean, integer, ...) and mode (read or read_write), then read 
the variable's value. 

• Set a value into a variable. Variables are created when set, if necessary. 

• Get and display all currentiy defined variable names. 

• Display a variable's value, read a user input value, and set the variable. That is, convert 
to/ftom a string value from/to a variable's value. 

• Remove a variable from active memory. 

V-4.2.1 Read and Set an Environment Variable's Value 

Calls Used: 

Environment_Mgt . Get_var_type 

Gets the type of a named variable. 

Environment_Mgt . Get_var_mode 

Gets the mode (read or read_write) of a named variable. 

Environment_Mgt . Get_jype 

Gets a value Irom a variable of the named type. 

Environment_Mgt . Setjtype 

Sets a value into a variable of the named type. 

Text_IO . Put Puts a string or character value out to the standard output. 

Text_lO . Get Gets a string or character value from the standard input. 



The following program fragment shows how to read the type and mode of a variable, given a 
variable name. 

If the given variable is of CL_Def s . integer_type, this program will read the variable's 
current value. If the variable is in CL_Def s . read_write mode, this program will incre- 
ment the value by one, and then store the incremented value back into the integer variable. 
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(from Manage_Application_Environment_Ex.sb) 

25 variable_name : System_Defs.text { 
2 6 CL_De f s . max_name_sz ) ; 

27 variable_type : CL_Defs.var_type; 

28 variable_mode : CL_Defs.var_mode; 

32 integer_value : integer; 

81 Text_IO. Put ("Enter a variable name:" ); 

82 

83 Text_IO.Get (variable_name .value) ; 

84 

85 variable_type := Environment_Mgt.Get_var_type ( 

86 var_name => variable_name) ; 
87 

88 variable_mode := Environment_Mgt .Get_var_mode ( 

89 var_name => variable_name) ; 
90 

91 if variable_type = CL_Def s . integer_type then 
92 

93 integer_value := Environment_Mgt .Get_integer ( 

94 var_name => variable_name) ; 

102 if variable_mode = CL_Defs.read_write then 

103 integer_value := integer_value + 1; 

120 end if; — if "read_write" 

159 end if; — if "integer_type" 

V-4.2.2 Display all Environment Variable Names 

Calls Used: 

Environment_Mgt . Get_all_naines 

Gets the names of all currently defined variables. 

Text_lO . Put Puts a string value out to the standard output. 



The following program fi^agment shows how to read the names of all local variables, then put 
each name to the standard output. 
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{ from Manage_Appl icat ion_En vi ronment_Ex . sb ) 

25 variable_name : System_Defs.text ( 
2 6 CL_Def s . max_name_sz ) ; 

30 variable_name_list : System_Defs. string_list (1000) ; 

57 Environment_Mgt .Get_all_names ( 

58 group_name => System_Defs .null_text, 

59 list => variable_name_list, 

60 global => false); 
61 

62 Text_IO.Put_line("List of local variables:"); 

63 

64 for i in 1 .. variable_name_list .count loop 

65 

66 String_List_Mgt .Get_element ( 

67 from => variable_name_list , 

68 el^os => i, 

69 element => variable_name) ; 
70 

71 Text_IO.Put_line(variable_name. value) ; 

72 

73 end loop; 

V-4.2.3 Get and Set Environment Variable Vaiues in ASCIi 

Calls Used: 

Environinent_Mgt . Convert_and_get 

Gets an ASCII representation of a variable's value. 

Environment_Mgt . Convert_and_set 

Sets a variable from an ASCII representation of the value. 

Text_IO . Put Puts a string or character value out to the standard output. 

Text_IO . Get Gets a string or character value from the standard input. 



The following program fragment asks for a variable name, then reads the type and mode of the 
variable. The current value of the variable is read as an ASCII representation, and displayed. 

If the variable is in CL_Def s . read_write mode, the user is prompted to enter a new 
ASCII representation for the variable's value. The entered value is then set into the variable. 
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( from Manage_Applicat ion_Environment_Ex . sb) 

25 variable_name : System_Defs.text { 
2 6 CL_Def s .max_name_sz ) ; 

27 variable_type : CL_Defs.var_type; 

28 variable_mode : CL_Defs.var_mocie; 

33 ASCII_value: System_Def s. text (1000) ; 

34 answer: character; 

81 Text_IO. Put ("Enter a variable name:" ) ; 

82 

83 Text_IO . Get ( var iable_name . value ) ; 

84 

85 variable_type := Environment_Mgt . Get_var_type ( 

86 var_name => variable_name) ; 
87 

88 variable_mode := Environment_Mgt .Get_var_mode ( 

89 var_name => variable_name) ; 

124 Environment_Mgt . Convert_and_get ( 

125 var_name => variable_name, 

126 value => ASCII_value) ; 
127 

128 Text_IO. Put ("Value of "); 

129 Text_IO.Put ( var iable_name .value) ; 

130 Text_IO.Put (" variable is:"); 

131 Text_IO.Put_line (ASCI I_value. value) ; 
132 

133 if variable_mode = CL_Defs.read_write then 

142 Text_IO. Put ("Enter new value:"); 

143 Text_IO.Get (ASCII_value .value) ; 
144 

145 Environment_Mgt .Convert_and_set ( 
14 6 var_name => variable_name, 

147 value => ASCII_value, 

148 var_type => variable_type) ; 

152 else 

153 Text_IO. Put ("Mode of ") ; 

154 Text_IO.Put ( var iable_name .value) ; 

155 Text_IO.Put_line(" variable is 'read-only'."); 
156 

157 end if; — if mode = read_write 

V-4.2.4 Create and Remove an Environment Variable 

Calls Used: 

Environment_Mgt . Setjtype 

Sets a value into a variable of the named type. The variable is created if it 
does not already exist. 

Environment_Mgt . Remove 

Removes a variable. Locally created variables (OEO and status) and 
loop variables (for i in range) cannot be removed. 



The following program fragments create a new local integer variable, named 
"new_integer". The new variable may be read or set as needed by the program. At the end 
of the program, the variable is removed (since it was a local variable, it would have dis- 
appeared at program termination anyway). 
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( from Manage_Appl icat ion_En vi r onment_Ex . sb ) 

25 variable_name: System_Defs.text ( 

26 CL_Defs.max_name_sz) ; 

4 4 Text_Mgt . Set ( 

4 5 dest => variable_name, 

4 6 source => "new_integer") ; 

47 

4 8 Environment_Mgt . Set_integer ( 

4 9 var_name => variable_name, 

50 value => 0, 

51 mode => CL_Defs .read_write, 

52 global => false); 

164 Text_Mgt . Set ( 

165 dest => variable_name, 

166 source => "new_integer") ; 
167 

168 En vir onment_Mgt . Remove ( 

169 var_name => variable_name, 

170 quiet => true, 

171 global => false); 



V-4.3 Summary 



• Variables have a name, a type, a mode, and a value. The variable's type is one of the six 
CL types: boolean, string, . . ., The variable's mode is either read_only or 
read_write. The variable's value is of the appropriate type. 

• Command language (CL) variables control aspects of the current CLEX instance (such as 
message type and language) and contain information for use by jobs and programs (such as 
the current directory). 

• Global variables are inherited by subsequent jobs and processes in this session. Local 
variables are specific to the creating job. 

• System and user environment variables in passive store are maintained by the 

manage . variable_groups utility. 

• Environment variables may be set and changed using commands common to CLEX and the 
command handler service: create . variable, set . variable, list . variable, 
and remove .variable. 

• Environment variable values can be read procedurally in two ways: as a value of the correct 
type (Get_type calls) or as an ASCII representation of the value (Convert_and_get 
caU). 



• 



Enviroimient variable values can be set procedurally in two ways: with a value of the 
correct type (Set_type calls) or with an ASCII representation of the value 

(Convert and set call). 
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This chapter describes how to use menus defined by the Window_Services package. 
Menus are created procedurally using Data_Def initionjMgt. The resulting menu data 
definition {menu DDef) is stored under a pathname. This chapter describes some design con- 
siderations for menus and the procedural aspects of menu usage but does not describe the menu 
editor utility itself. 

Packages Used: 

Character_Display_AM 

Provides device-independent I/O to character display devices such as 
printers, plotters, and windows on character and graphics terminals. 

Window_Ser vices 

Provides windows on character and graphics temiinals, including pull- 
down menus. 



This chapter describes the following tasks: 

• How to define a menu group. 

• How to install and enable (display) a menu group in a window. 

• How to determine the menu choice made by a user. 

• How to change or remove a displayed menu group. 

Figure V-5-1 shows a menu group in a window, with one of the menus currently selected. 
This figure also shows the relationship between the window service (which provides the menus 
and the window), the terminal access method (which returns the user's selection), and your 
BiiN™ program. 
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Figure V-5-1. BiiN™ Application Program and Menus 
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V-5.1 Concepts 

• Each menu is part of a menu group - a menu group contains one or more menus. 

• A window can have only one menu group enabled - several menu groups can be installed in 
one window, but only one menu group is enabled at any time. 

• A menu has a title and one or more menu items - the user selects a menu title, causing that 
menu to appear, then selects one item from the menu. 

• Each menu item has a number and a string - the menu item's string is displayed, and the 
menu item's number is returned when the item is selected. The returned menu item's 
selection record contains three numbers: the menu group, menu, and menu item numbers. 

• Menu items may be picked by the cursor or by index - to choose an item, the user either 
moves the cursor onto the item and presses <TBD> or enters the displayed item's index 
number. 

• Menu items may have associated "help" messages - the user can request an explanation of 
any menu item. The associated "help" message is displayed by the menu service, without 
program intervention. 

• Some special function keys are used with menus - each implementation of menus defines its 
own. 

• Windows and this type of menu are provided by the window service - in the 
Window_Services package and its . Ops nested package. 

• Menu item selections are input events - the character display access method 

(Char act er_Display_AM package) provides a Read call to read such events. Your 
program may read a menu item selection, a keyboard or mouse event, or any of the 
window-related events (see Terminal_Def s . input_enum for a complete list of 
awaitable terminal input events). Note that mice are not supported by the character display 
access method. 

V-5.1 .1 Why Use Menus? 

Menus provide an easy, standardized way to interact with the user: 

• Menus provide a common display and user input format. 

• There are no commands for the user to learn or remember. 

• The user selects a menu item, without program intervention, resulting in one or more menu 
selections to be read. 



V-5.2 Techniques 

After reading this section, you wiU be able to: 

• Define a menu group 

• Install a menu group in a window 

• Get the user's menu item selection 

• Set a checkmark: for a menu item 

• Change a window's enabled menu group 
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• Remove a menu group from a window. 

For infonnation about creating and using windows, see Chapters IV-4 and IV-5. 

V-5.2.1 Define a Menu Group 

As part of program development, the menus to be used are defined. Design considerations 
when creating menus and menu groups include: 

• Determining the logical operation to be performed by each menu selection. 

• Grouping logically related items into menus. Each menu should contain from 2 to 10 menu 
items. (More than 10 menu items may be cumbersome for the user.) 

• Grouping logically related menus into menu groups. 

• Determining possible sets of menu groups: a menu selection may lead to a new menu 
group, under program control. 

Each menu group, and its associated menus and their menu items, is created by calls to the 
DDef procedural interface (Data_Def inition_Mgt package). 

The Make_Menu_DDef _Group_Ex package, in Appendix A, shows how to procedurally 
create a simple menu group, containing two menus and five menu items: Menu 1 has two 
menu items; Menu 2 has three. 

After being created, the menu group's DDef may be stored under a pathname. Your program 
then retrieves the menu group's DDef later by its pathname. The menu group is inst^ed in a 
window and enabled, as described in the next section. 

To change a menu item's text during program execution, call 

Window_Ser vices . Replace_menu_item_text. 

The following program fragment defines a menu group, menu, and some of the menu item 
numbers. These constants are used by the program to interpret a menu selection record (see 
"Get a Menu Selection", below). 
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(from Inventory_Menus specification) 

74 inv_menu_group_ID : constant 

75 Terminal_Defs .menu_group_ID := 1, 

80 inquiry_menu_ID: constant 

81 Terminal_Defs.menu_ID := 1; 
82 

83 posting_menu_ID : constant 

84 Terminal_Defs.menu_ID := 2; 
85 

86 update_menu_ID: constant 

87 Terminal_Defs.menu_ID := 3; 
88 

89 report_menu_ID: constant 

90 Terminal_Defs.menu_ID := 4; 
91 

92 housekeeping_menu_ID: constant 

93 Terininal_Defs.menu_ID := 5; 
94 

95 exit_menu_ID : constant 

96 Terminal_Defs .menu_ID := 6; 
97 

98 — Inquiry menu items 

99 inq_by_part_item: constant 

100 Terminal_Defs.menu_item_ID := 1 

101 inq_by_ciesc_item: constant 

102 Terminal_Defs.menu_item_ID := 2 

103 inq_exit_item: constant 

104 Terminal Defs.menu item ID := 3 



V-5.2.2 Install a Menu Group in a Window 

Calls Used: 

Window_Ser vices . Install_menu_group 

Installs a menu group in a window. 



The following program fragment retrieves the stored menu group's DDef, then installs the 
menu group in a window. 

(from Inventory_Menus body) 

30 menu_group_DDef_AD: Data_Def inition_Mgt .DDef_AD; 
33 menu_group_node : 
34 Data_Definition_Mgt .node_reference; 

4 6 menu_group_DDef_AD := DDef_from_untyped ( 
4 7 Directory_Mgt . Retrieve ( 

4 8 name => menu_group_DDef j>ath) ) ; 

53 menu_group_node := Data_Def inition_Mgt . 

54 Retrieve_DDef ( 

55 DDef => menu_group_DDef_AD, 

5 6 name => menu_group_DDef_root_name) ; 

61 Window_Services .Ops . Install_menu_group ( 

62 window => Inventory_Windows . 

63 main_window, 

64 menu_group => menu_group_node, 

65 ID => inv menu group ID) ; 
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V-5.2.3 Enable an Installed Menu Group 



Calls Used: 



Window_Services .Ops .Menu_group_enable 

Displays the menu group and enables user menu item selectiono 



The following program fragment enables the menu group installed in the previous section. 

(from Inventory_Menus body) 

69 Window_Services .Ops .Menu_group_enable ( 

70 window => Inventory_Windows . 

71 main_window, 

72 menu_group => inv_menu_group_ID, 

73 enable => true) ; 

V-5.2.4 Get a Menu Selection 

Calls Used: 

Character_Display_AM . Ops . Set_input_type_mask 

Determines the allowable types of user input fiom a window, including 
menu item selection. 

Char act er_Display_AM. Ops .Read 

Reads an input event from a window. 



The following program fragment defines the types and variables for getting a menu selection. 

(from Inventory_Main) 

79 menu_select: Terminal_Def s .menu_selection; 

86 event_type: Terminal_Def s. input_enum; 

90 event_num: System. ordinal; 

The following program fragment sets the window input mask to menu_item_picked, waits 
for the user's menu item selection, then calls the appropriate subprograms to perform the 
selection. 
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(from Inventory_Main) 

125 Character_Display_AM.Ops.Set_input_type_mask( 

126 opened_ciev => Inventory_Windows .main_window, 

127 new_mask => Terminal_Defs. input_type_mask' ( 

128 Terminal_Defs.memj_item_picked => true, 

129 others => false)); 

139 Character_Display_AM. Ops. Read ( 

140 opened_dev => Inventory_Windows .main_window, 

141 buffer_VA => menu_select' address, 

142 max_events => 1, 

143 max_bytes => 0, 

14 4 block => true, — Wait . . . 

14 5 type_read => event_type, 

14 6 nuin_read => event_num) ; 

151 case menu_select .menu is 
152 

153 when Inventory_Menus . inquiry_menu_ID => 

154 Inventory_Menus .Process_inquiry_menu ( 

155 selection => menu_select .item) ; 

V-5.2.5 Display a Checkmark for a Menu Item 

Calls Used: 

Wind.ow_Services . Ops .Menu_item_check 

Displays a check mark (V) next to a given item in a menu. 



Your program can display a (tenninal-dependent) checkmark next to that menu item. The 
checkmaik can indicate that the item is or was selected. For example, a menu of attributes for 
an object may have several attributes selected, with the selected attributes' menu items check- 
mariced. 

V-5.2.6 Change a Window's Enabled Menu Group 

Calls Used: 

Window_Ser vices . Ops .Menu_group_enable 

Enables or disables an installed menu group in a window. 



To disable the currently enabled menu group, call 

Window_Services . Ops .Menu_group_enable with the enable parameter false. 

To enable another installed menu group in a window, just call 

Window_Ser vices . Ops . Menu_group_enable for that menu group, with the enable 

parameter true. This implicitly disables the previously enabled menu group. 

V-5.2.7 Remove an Installed Menu Group from a Window 

Call Used: 

Window_Ser vices . Ops . Remove_menu_group 

Removes an installed menu group from a window. 
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Call Remove_menu_group to remove an installed menu group. There is no change to any 
other installed menu groups (that is, none become enabled). 

V-5.3 Summary 

• Menus provide a consistent, easy-to-use user interface. 

• A menu contains a menu title and one or more menu items. 

• A menu group contains one or more menus. 

• A window can have several menu groups installed, but only one menu group at a time can 
be enabled. 

• After a menu group is installed and enabled, menu selections and menu "help" messages 
are displayed without program intervention. 

• After the user has made a selection, an input event is available, containing the chosen menu 
group, menu, and menu item numbers. 



V-5-8 Programming with Menus 



FKELIMIINAKY 



UNDERSTANDING FORMS 



6 



Contents 



Creating a Form Description V-6-4 

Record I/O V-6-4 

Form Elements V-6-4 

Texts V-6-5 

Screen Fields V-6-5 

Character Fields V-6-5 

Option Fields V-6-7 

Enumeration V-6-7 

Null Enimieration Element V-6-9 

Protecting Fields V-6-9 

Data Fields V-6-9 

Subfonns V-6-9 

Groups V-6-9 

Piles V-6-10 

Expansion and Contraction of Forms V-6-12 

Subroutines and the Subroutine Interface V-6-13 

Processing Routines V-6-14 

Key Catchers V-6-15 

Symbolic Keys V-6-16 

Key Lists V-6-19 

Form Name Environments V-6-19 

Execution Paths V-6-20 

Explicit Modification of the Path Registers V-6-21 

Imphcit Modification of the Path Registers V-6-21 

Messages and Help Information V-6-21 

Window Management V-6-22 

Summary V-6-22 



Understanding Forms V-6-1 



The forai service provides means to create, modify, test and execute forais which can be used 
interactively. Forais the fomi service displays on screens have the same general appearance as 
forais printed on paper that are frequently encountered in everyday transactions. Unlike paper 
forms, the forms created and controlled by the form service and directed by a high-level ap- 
plication program can perform a wide variety of functions dependent on the needs of the user 
and nature of the form. 

Traditionally, a form has been a printed document with labelled spaces provided for writing in 
information. A typical paper form is shown in Figure V-6-1. 
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Figure V-6-1. Sample Paper Form 



The form service builds on this concept to provide interactive forms capabilities on a terminal. 
For example, the cursor, which marks the current position in the form, may be moved back a 
space to erase an incorrect character, or back to the previous field to reenter a value. The 
contents of part of the form can be altered depending on the value of a previously entered field. 
Intermediate values can be calculated and stored transparently until needed later by the form. 
Even the order of execution of the fomi can be altered dynamically depending on the data 
entered. 

This chapter describes the various parts of an interactive form and how they are combined into 
a single, executable form as shown in Figure V-6-2. 
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PARTS FILE INFORMATION 

I 
alphanumeric field 



texts 

I I 

Part ID: 3512734 Description: 1/2" aluminum conduit 



Location: 02-F12 

Qty on hand: 500 

Reorder point: 750 

Reorder qty: 2000 

Supplier ID: RohmCo 

Average unit cost: $1.86 

Last unit cost: $1.65 < 

Date first activity: 1985-06-25 < 



Unit: feet < overlaid enumeration 

Usage this month: 375 < 

Usage this year: 6250 

Usage last year: 94 75 
StanEfCo 



numeric 
field 



< — group with 

three instances 



numeric field 

datefield 

Date last activity: 1987-03-13 Status: REORDER 

Delete this part (press <Return> to affirm) ? DELETE 

I 
optionfield 



Figure V-6-2. Annotated Executable Form 



This section describes the form parts available for constructing an executable form. The next 
chapter, V-7 describes how an executable form is controlled. 

Packages Required: 

Form_Def s Defines types and constants used by the Form_Handler package. 

Form_Handler Provides calls to process, control, and change forms. 

Form_Def s contains the definitions for fonn properties (such as character display 
characteristics), symbolic keys (control keys, application keys, and information keys), and 
other definitions which describe the physical attributes and current operational status of a form. 

Forin_Handler provides calls to: 

• Open and close a form. 

• Execute a form. 

• Modify data and control the execution networic path. 

• Query the state of the form, a form element, or the last user interaction. 
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V-6.1 Creating a Form Description 



A forai can be created with edit . form (the form editor), create . form, or procedurally 
with the Data_Def inition_Mgt package. 

The fomi editor is an interactive tool that enables a form developer to interactively create and 
modify form descriptions. This tool enables a form developer to design a form directly on the 
terminal screen and to define the properties for each form element as it is drawn and 
positioned. Etetailed information for using the form editor is given in the BzW™ Systems Form 
Editor Guide. Upon successful completion of an editing session, the form editor generates an 
executable form description, 

create . form automatically creates the most simple, default form design based on a file's 
associated record description. The resulting form description can be used as input to the form 
editor for tailoring the form to the user's needs, or be executed as is. 

Both the form editor and create . form generate a form description which can be executed 
by a user and controlled by Form_Handler calls. 

Every form is represented as a/orm DDef. (Form description is a higher-level synonym for 
form DDef.) The form DDef defines the elements of a form, their order of execution, display 
attributes, location, etc. Application programmers will normally use the form editor to create a 
form description. Form descriptions can also be created procedurally using 
Data_Def inition_Mgt although this method requires a detailed understanding of DDefs 
and is, therefore, not recommended. This low-level procedural interface is mainly of interest 
to implementors of interactive applications that create forms at runtime. 

Form descriptions are stored with a directory entry and consequently are retrieved with 
Directory_Mgt . Retrieve when their AD is needed for calls such as 

Form_Handler .Open_f orm. 



V-6.2 Record I/O 



If record I/O is used for executing a form, a record description must be associated with the 
form. A record description describes the structure of a communication area used by an ap- 
plication program to communicate with an executing form. The primary benefit of employing 
record I/O is ease of use. It may not be appropriate for more complex applications for which 
Form_Handler calls are more effective. 

If aU or most of the screen fields that a form will use are already defined in an existing record 
description, associating a form with the related record description is usually the most effective 
means for transferring data. Given an associated record, Form_Handler can store and 
retrieve the data from the form and record with single caUs. When a form is not associated 
with a record description, the data for each screen field must be stored and retrieved with 
individual Form Handler calls. 



V-6.3 Form Elements 

A form may consist of the foUomng form elements: 
• Texts 
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Screen fields 

Enumerations 

Subforms 

Groups 

Piles 

Data fields 

Subprogram interfaces 

Processing routines 

Key catchers 

Key lists. 

The first five fomi elements (texts, screen fields, enumerations, subfonns and groups) are 
called sheet elements. The remaining form elements affect the appearance of the form (piles), 
hold intermediate data values (data fields), and affect the execution of the form. The sheet 
elements are visible elements in the screen image of the form, called a form sheet. The form 
sheet is the rectangular area displayed on the screen. 



V-6.4 Texts 



Texts are strings which commonly serve as labels for screen fields. In Figure V-6-3, the string 
Part ID : is an example of a text in such a use. Texts may also be used independently for 
other purposes such as column headers or explanatory text. 



V-6.5 Screen Fields 



Screen fields are areas defined on the form sheet for receiving or storing user input. Screen 
fields include: 

• Character 

• Option. 



V-6.5.1 Character Fields 



Character fields are areas defined on the form sheet in which a user may enter data. Figure 
V-6-3 illustrates an character field with an associated text string. 



Part ID: 



Figure V-6-3. Character Field 



A screen field is not required to have an associated text. 
Character fields are of the following kinds: 
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• Numeric 

• Alphanumeric 

• Date. 

Numeric fields have fixed lengths. Internally, they arc represented as 4-byte integer, 8-byte 
integer, or 8-byte real. Alphanumeric fields may be of fixed or variable length depending on 
how they are defined. 

The size of a numeric field on the screen depends on the format definition. There are no 
fonnats for alphanumeric fields. Table V-6-1 illustrates examples of numeric field formatting. 
See the BUN™ Systems Form Editor Guide for detailed instmction on formatting numeric 
fields. 





Table V-6-1. 


Examples of Numeric Formatting 


Field 
Contents 


Format 
String 


Clear When 
Zero 


Leading 
Text 


Trailing 
Text 


Di^layed 


10.34 


99999.99 


irrelevant 






00010.34 


10.34 


Jinitmnt^g^ 


irrelevant 






*** 10.34 


54ia34 


77..777..99 


irrelevant 






5.410.34 





99999.99 


not set 






00000.00 





99999.99 


set 








10.34 


7.777.9.99 


irrdevant 


** 


** 


** 10.34** 


10.34 


**«iii9^p 


irrelevant 


$ 




$***10.34 


1134 


ZZ9.9999999E+99 


irrelevant 






113400000E+00 


-1134 


-9.999999eZZZ+ 


irrelevant 






-1.234000E 1+ 


10.34 


+0.999999E+99 


irrelevant 






+0.103400E+02 
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A date field is a special case of an character field. 

Data fields require a format string. The fonnat string is comprised of replacement characters 
and insertion characters. Replacement characters may include: 

YY - Last two digits of a year. 

YYYY - All four digits of a year. 

MM - Integer value of a month. 

MMM - Abbreviation of a month. 

DD - Interger value of a day. 

DDD - Abbreviation of a day. 

HH - Integer value of hours. 

II - Integer value of minutes. 

SS - Integer value of seconds. 

Insertion characters are printable characters that provide explanatory text or punctuation. Ex- 
amples of data formatting showing the use of replacement and insertion characters are il- 
lustrated in Table V-6-2: 
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Table V-6-2. Examples of Date Formatting 



Field 
Contents 


Format 
String 


Disj^layed 


19841128 120109 


YYYY-MM-DD 


1984-11-28 


19841128120109 


YYYY:Mmm:DD 


1984:Nov:28 


19841128 120109 


Yeanyyyy Month:Mmm Day:dd 


Yean 1984 Month J^ov Day:28 


19841128 120109 


DDMMYY 


28 11 84 


19841224 120109 


DDD-YYYY 


359-1984 


1984112812 0109 


HHHrSS 


12:01:09 


19841128 120109 


mj 


701/ 


19841224120109 


DDD days HH iiours 


359 days 12 hours 



The contents of a date field are automatically validated after entry. If the contents of a part of 
the field are invalid, the local cursor is positioned at the beginning of that part. 

Default fomiats for these varieties of screen fields are shown in Table V-6-3: 

Table V-6-3. Default Screen Field Formats 



Default Format 


Type 


-ZQZZZZZ9 


int4 


-777.7,7,7.777,7,1777,7X79 


int8 


-9.9999999999E-99 


real8 


yyyy-mm-dd 


date 



V-6.5.2 Option Fields 



An option field is composed of a visible text string which may be selected and deselected with 
a symbolic key or a mouse. The actual data transmitted is a boolean value indicating whether 
or not the field is selected. Figure V-6-4 illustrates an option field. 



Delete this part (press <Return> to affirm)? DELETE 
Figure V-6-4. Option Field 

In Figure V-6-4, the DELETE string is an option field. An option field is highlighted when 
selected (true) and displayed in normal intensity when not selected (false). An option field is 
selected and deselected with the <select IocaI> key. 



V-6.6 Enumeration 



Enumerations are sheet elements consisting of an ordered set of values. The values of an 
enumeration are represented with texts. Each enumeration is assigned a nonnegative integer 
value. Each tuple (value, screen representation) is called an element of the enumeration. If an 
element's representation is empty, the element is called the null element of the enumeration. 

Enumeration elementss are selected with the <select local> key. When selected, the element is 
highlighted. Any previously selected element of the enumeration is simultaneously remmed to 



Understanding Forms 



V-6-7 



rKliLlMlINAKI 



nonnal intensity. The value of the currently highlighted element is the value assigned to the 
enumeration when the enumeration is left Characters cannot be entered into enimieration 
elements. 

Enumerations may be one of two kinds: overlaid and scattered. 

An overlaid enumeration is an enumeration in which the enumeration elements are displayed 
one at a time. The user toggles through the enumerations by using the <select Iocal> key. The 
enimieration element currently displayed when the enumeration is left (commonly by pressing 
the <next> key) defines the value which will be assigned to the enumeration. 

Figures V-6-5 and V-6-6 illustrate the first two enumeration elements of an overlaid enumera- 
tion field with the text title Unit: and four imits of measure as enumeration elements. 



Unit: each 

Figure ¥-6-5. Overlaid Enumeration: Initial Value 

After the user presses <select locaI>, the second enumeration value, feet, overlays the first 
enumeration value, each. 

Unit: feet 

Figure V-6-6. Overlaid Enumeration: Subsequent Value 

Each time <select Iocal> is pressed, the next enumeration element will overlay the previous 
element until the last element is overlaid with the first and the cycle begins again. 

A scattered enumeration is an enumeration in which all of the enumeration elements are dis- 
played simultaneously. The screen representations of the elements are arranged within the 
reaangular area allocated to the enumeration. The element whose value represents the current 
value of the enumeration is highlighted while all other elements are displayed in the display 
attributes defined for the enumeration. Figure V-6-7 illustrates a scattered enumeration. 



Unit : each feet 
lb inch 

Figure V-6-7. Scattered Enumeration 

The figure shows that the feet element is highlighted and, therefore, currently selected. 

The local cursor can be moved from a screen field or enumeration to a scattered enumeration 
with the <next>, <next with clear> or <previous> keys. Once the cursor is in a scattered 
enumeration the <next>, <next with clear> or <previous> keys move the cursor between the 
enumeration elements. The element at which the cursor is positioned can be selected with the 
select local> key. The currently selected element is highlighted and the previously 
selected element (if any) is returned to normal intensity. The enumeration element currently 
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highlighted when the enumeration is left defines the value which will be assigned to the 
enumeration. 

V-6.6.1 Null Enumeration Element 

A null element of an enumeration is an element which is associated with the value empty, 
meaning no value selected. An enumeration may or may not contain a null element. In an 
overlaid enumeration, the null element, if present, must have a screen representation (possibly 
containing only spaces). 

If a scattered enumeration has a null value which is not assigned a screen representation, it can 
be selected with the <delet e> key. If the enumeration has a null value that is represented on 
the screen, the value is selected like any other value. 



V-6.7 Protecting Fields 



Screen fields that are created with \h& protected property are used only for output 
Form_Handler . Store_value is used to place the new value into the form. They are not 
included in the network of paths (see the "Execution Path" section for more information on a 
form's network of paths). These protected fields can be used, for example, to display the 
results of a calculation or logic decision. On the screen, they would appear the same as any 
other character field, but the user cannot enter data into them. 



V-6.8 Data Fields 



Data fields are not defined on the form sheet and are, therefore, not visible. They are used as 
storage areas for data used in computations or for exchanging data between processing 
routines, key catchers, and the application program. 



V-6.9 Subforms 



A subform is a form included in another form. This sheet element is provided as a con- 
venience for making complex forms out of simpler forms. A subform can be created once and 
referenced by several other forms and subforms. Subforms may contain all the form elements 
allowed in a form, and may be nested. 



V-6.10 Groups 



A group is a subform which may be replicated. Each replication is called an instance of the 
group. The initial number of instances of a group is defined when the form is created, and may 
be modified during execution. Groups may contain any elements which may be used in a form 
including texts, screen fields, subforms, other groups, piles, processing routine calls, and key 
catcher calls. 

For example, when the user enters the first supplier ID and leaves the field by using an 
application-defined key (that calls Form_Handler . Create_group_instances) rather 
than the usual key such as <next>, a second instance of the group is created so that the user, in 
this case, can enter a second supplier ID. In the sample form, a maximum of three instances 
can be displayed for character field for a supplier identification. Figure V-6-8 illustrates this 
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group showing supplier IDs entered into the first two instances of the group, and the third 
instance created and awaiting entry of data. 



Supplier ID: RohmCo StanEfCo 



Figure V-6-8. Group Instances 



Groups are deployed (displayed) horizontally to the right, or vertically and downward. Figures 
V-6-9 and V-6-10 illustrate the two deploying directions for group instances. (The group 
shown in Figure V-6-8 is deployed horizontally.) 



instance #1 | instance #2 I instance #3 



Figure V-6-9. Group Instances in a Horizontal Deployment 

Groups may contain multiple sheet elements as shown in Figure V-6-10. These group in- 
stances contain name strings (alphanimieric fields), an enumeration of two values (Sex) and a 
numeric field with two insertion characters (SSN#). 



Last Name First Name Sex SSN# 

M F . - - 



M F 


- - 


M F 


- - 


M F 


- - 



Figure V-6-10. Group Instances with Multiple Sheet Elements 

The number of instances of a group can be varied before or during the execution of the form 
with Form_Handler .Create_group_instances and 

Form_Handler . Remove_group_instances fi*om within processing routines, key 
catchers or the application program. 

The maximum number of instances of a group can be set by the form programmer when the 
form is created or modified. The number of instances of a group may be zero. In this case, the 
group occupies an area the size of one character (unless the group is a member of a pile in 
which case it occupies no space at all). 

V-6.11 Piles 

A pile is a sheet element occupying an area in a form in which other sheet elements can reside. 
Piles give the form designer control over the appearance of a form by specifying a fixed area of 
the form in which a choice of elements can be displayed. 

While the locations of sheet elements not on a pile are determined directly by coordinates, 
piles offer an indirect method of positioning. A pile is a layout feature and cannot be executed. 
Processing routines or key catchers can be used to display pile elements. The order of execu- 
tion of sheet elements is not affected by their being on a pile. 
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Piles, therefore, serve two primary functions. First, they reserve one area on the form for use 
by elements selected by the forms designer. Second, the pile's reserved area can be sized 
sufficiently for the anticipated maximum expansion of its variable-length elements so that 
expansion will not dislocate neighboring sheet elements thereby altering the appearance of the 
form. (Read about expansion and contraction of a form in the next section.) 

When a pile is defined, one or more sheet elements arc assigned to it. The order in which they 
are listed specifiies their relative position or rank. Processing routines and key catchers deter- 
mine which of the elements of pile are to be displayed. The selected pile elements are dis- 
played in a horizontal or vertical deployment (specified when the pile is defined) in the order 
of their rank. 

For example, a form determines which elements are to be displayed in a field depending upon 
whether the individual is (1) married and male, (2) married and female or (3) not married. The 
elements defined for the pile in this form include: 

• Given Name of Spouse 

• Premarital Name 

• Age 

• Separate Household 

This example describes a form used to collect personal data. The following figure shows the 
form (without the specific pile elements shown). 



Name: Given Name: 

I male | female | I married I 



o, 



[pile] 



Address 



Figure V-6-11. Form with a Pile 



The following sheet elements is displayed in the pile of the form when "female" and "married" 
have been selected. (The deployment is vertical.) 



o 

. Given Name of Spouse : 
. Premarital Name: 



Figure V-6-12. First Pile Usage 
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The following fonii element is displayed in the pile of the form when "male" and "married" 
have been selected. 



o 

. Given Name of Spouse: 



Figure V-6-13. Second Pile Usage 



The following fomi element is displayed in the pile of the fonn when "married" has not been 
selected. 



o 

+ + 

. Age: I separate household I 

+ + 



Figure V-6-14. Third Pile Usage 



Piles may not be nested, but a group containing a pile may be located on a pile. Groups having 
no instances and a default instance of zero occupy an area the size of one character on a pile. 
Otherwise the area occupied is determined by the number of default instances. 

V-6.12 Expansion and Contraction of Forms 

Variable size sheet elements (alphanumeric screen fields of variable length and, optionally, 
piles and subforms) can expand beyond their default size when data is being entered into them. 
When they do expand horizontally, all of the sheet elements whose left boundaries are located 
right of the right border of the expanding element are automatically moved to the right. 
Likewise when they expand vertically, sheet elements whose upper boundaries are located 
beneath the lower boundary of the expanding element are automatically moved down. Thus, 
sheet elements are kept fix)m being obscured by neighboring expanding elements. In table-like 
forms, column and line relationships are preserved. 

If a sheet element is about to expand over the boundary of the form sheet, the form sheet 
expands; that is, the rectangular area occupied by the form sheet within the window's frame 
buffer expands. When the form sheet is constrained by the size of the fi-ame buffer, it can no 
longer expand. All subsequent operations which require expansion of a sheet element are 
rejected. 

Expansion of sheet elements not included within subforms and groups always affects subforms 
and groups as a whole unit. For example, a variable-length alphanumeric field that expands 
into the upper-left comer of a group instance will move all elements of the group as a unit 
regardless of whether any individual group element is in the path of the expanding field. The 
area that a subform or group instance occupies may grow if the group contains elements of 
variable size such as an alphanumeric screen field, group or pile. 
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When a form expands or contracts, the rectangular area containing a scattered enumeration is 
relocated as a whole unit. 

If the deploying direction of a group is horizontal and if one or more instances of the group 
grows, instances with higher instance indexes are moved to the right but do not change their 
size. Figures V-6-15 and V-6-16 illustrate the effect of the growth of a group instance. In- 
stance #1 grows horizontally, and instances #2 and #3, which do not change in size, move to 
the right. 



instance #1 I instance #2 I instance #3 



screen field 



Figure V-6-15. Effect of the Expansion of a Group Instance: Before Expansion 



instance #1 I instance #2 I instance #3 



screen field 



Figure V-6-16. Effect of the Expansion of a Group Instance: After Expansion 

The number of instances is restricted by the size of the frame buffer of the window in which 
the form is currently displayed. The frame buffer defines the limits of expansion for a fonn 
whether that expansion is by the addition of a group instance, or due to the expansion of a 
variable-length form element (such as an alphanumeric screen field). 

Contraction is the opposite of expansion. When a sheet element contracts, the form may or 
may not contract depending on whether the contracting sheet element was the sole cause of the 
expansion. Contraction commonly occurs after an alphanimieric field is left. The area oc- 
cupied by the field during data entry contracts to the rectangular size needed for displaying the 
current contents of the field or the size of the minimum area depending on which size is 
greater. 

An alphanumeric screen field first expands horizontally imtil it reaches the maximum line 
length (specified when the field was created) and then expands vertically. 

NOTE 

When an element of a group, a field is not constrained in its expansion by the deployment 
direction of the group. 

V-6.13 Subroutines and the Subroutine Interface 

Two kinds of subroutines may be used in a form: processing routines and key catchers. Sub- 
routines are incorporated into a form by specifying a subprogram interface. This interface 
specification contains: 

• The name of the subprogram interface definition 
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• The name of the image module in which the subprogram is contained 

• The name of the subprogram within the image module 

• Link option (1 ink_at_bind_t ime) 

• A description of the formal parameters of the subprogram. 

The name of the image module and the name of the subprogram within the image module are 
used to retrieve a sul^rogram value (an AD to a domain object plus a procedure entry offset). 
The subprogram value is retrieved by calling Link_By_Call . Link. The Form_Handler 
can then call the subprogram using the subprogram value. 

The link option is set during form development. When set false, the subprogram is not linked 
to the form description at bind time. This makes it possible to create, bind and test a form 
whose processing routines and key catchers are not yet available. The foim retrieves the 
subprogram value during the execution of the form when the subprogram is first called by the 
Form_Handler. When the link option is set to true, the subprogram is linked to the form 
description at bind time. 



Subroutines must be implemented according to the interlanguage calling conventions (see the 
BiiN^ Systems Programmer's Guide) for the language in which the subroutine is written) in 
order to be callable by the form service. Also, subroutines which are to be linked to forms 
must be image modules (see the BiiN^ Systems Linker Guide). 

V-6.14 Processing Routines 

Processing routines are subroutines written in high-level languages which are executable form 
elements. They can be used to: 

• Validate contents of screen fields 

• Control the order in which screen fields are entered 

• Modify contents of screen fields 

• Modify the appearance of the form sheet depending on user input 

• Perform any application-specific operations such as calculations. 

Processing routines are included in the network of the form execution path, and therefore, are 
caUed when the execution of the form reaches the point where they reside in the network. 
Processing routines may make Form_Handler caUs to: 

• Create and remove group instances 

• Change the display attributes of sheet elements 

• Store and retrieve field values 

• Alter the order of execution of the form 

• Call other forms. 

A processing routine call which has more than one successor in the form's netwoik of paths 
must have a next_path_element parameter defined in its subprogram interface in order 
for it to proceed. The actual value of this parameter specifies a path element. The value is 
stored in the next_pat h_element path register by Form_Handler. Form execution will 
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then continue at that element when the processing routine has finished executing. Processing 
routine calls with only a single successor must not have a next_path_element parameter. 

Another parameter of the interface is terminal_input. This parameter is a byte string 
which is interpreted as a sequence of symbolic keys by Form_Handler, and inserted into the 
stream of input keys replacing the last key processed. Processing routines and key catchers 
can simulate user input by writing into this queue with this parameter. 

More than one processing routine call may refer to the same subprogram interface. Therefore, 
a single processing routine may be called from several locations within a form's network of 
paths. 

The subprogram interface describes the formal parameters of the subroutine and the processing 
routine call describes the actual parameters. 



V-6.15 Key Catchers 



Key catchers are subroutines written in high-level languages which are activated by pre- 
defined keystrokes. They can be used to trigger entire functions with a single keystroke. A 
key catcher is assigned to a region of a form. A region defines the area of effectiveness of a 
key catcher. It may include a single screen field or enumeration, a group, a subform or the 
entire form. A single key catcher may be assigned to several regions, or several key catchers 
may be assigned to the same region. 

A subprogram interface for a key catcher is similar to a subprogram interface for a processing 
routine with the exception that a key catcher's interface does not include the 
next_jpath_element parameter, and does include the trigger_key parameter. 
trigger_key references an internal queue which contains the symbolic key that triggered 
the key catcher. 

A key catcher for which a subprogram interface has been specified is included into a form by 
defining a key catcher calU and assigning it to the form, a subform, a screen field or enimiera- 
tion. A key catcher call must have the following parameters: 

• The name ofthe subprogram interface. 

• A key list (a list of keys which are to be caught by the key catcher). 

• The actual parameters (the actual values of the formal parameters specified in the sub- 
program interface). 

When interpreting a keystroke, key catchers are scanned in the order in which they are as- 
signed in the form description. Generally, the first key catcher in such a list is assigned to a 
screen field, and secondary key catchers are assigned to the group or subform. The least 
significant key catcher is assigned to the region defined by the entire form. 

When the form user enters a character, the character is transformed into the corresponding 
symbolic key. Then the key lists ofthe effective key catchers are searched for that symbolic 
key according to the ordering of the key catchers. This search is performed for every entered 
character. The search stops when the symbolic key is found in a key list. Then the key catcher 
pertaining to that list is called. If the search does not succeed, the input character is processed 
by the Forin_Handler according to the type ofthe current sheet element 
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V-6.16 Symbolic Keys 



A symbolic key is a printable character, a control key, an application key or an information key. 
Printable characters correspond to the ASCII characters in the range 20 hex to 7E hex. A 
standard set of control keys are predefined in Form_Def s and enable the user to trigger 
functions used in typical form dialogues. An example of a symbolic key is <previous> which 
moves the cursor back to the previous screen field or enumeration. Application keys, which are 
also declared in Form_Def s, trigger application-defined functions. The application keys give 
the form developer the opportunity to customize the form with unique features. 

Information keys differ from the other symbolic keys in that they are input events from the 
terminal. These keys may be included into key lists and caught by application-defined key 
catchers. If they are caught by the Form_Handler, they do not trigger any action. 

Symbolic keys are used to mask differences among terminal keyboards thereby contributing to 
the device-independent benefits of using fomm services. The tables V-6-4, V-6-5 and V-6-6 
contain definitions for the symbolic keys. 

Table V-6-4. Control Keys 



Mnemonic Name 


Function 


Value (hex) 


abott_executi<m 


Aborts execution of the foim. 


0100 


backspace 


Moves the curscn* to the left by one space in 
the active screen field or one part in a date 
field. 


0101 


begiii_of_element 


Moves the cursor to the first character input 
position. 


0102 


begin_of_lme 


Moves the cursor to the first character posi- 
tion of the current line. 


0103 


bel 


Causes an audible or visible signal <m the 
tenninaL 


0104 


close_requested 


Requests that the form sheet window be 
closed. 


0105 


correct 


Displays the data input to a numeric screen 
field without formatting. This key has no 
effea <m nonnumeric screen fields. 


0106 


delete_character 


Deletes the character (or the part of a date 
field) under the cursor. 


0107 


delete_character_left 


Deletes the character to the left of the cur- 
sor. 


0108 


delete 


Deletes active screen field's input charac- 
ters, replacing them with null characters. 
Also, selects the null element (if any) of a 
scattered enumeration if the null element has 
no screen representation. 


0109 


down 


Moves the cursor to the next line in a 
multiple-line screen field. 


OlOA 


end_of_fonn 


Skips to the end of the form, or to the next 
compulsory screen field. Sets the 
destination path register to /END. 


OlOB 


forward_space 


Moves the cursor one space (or one part in a 
date field) to the right. 


OlOC 


global_help 


Displays help information f(»- the form. 


OlOD 


help 


Displays help information for this screen 


OlOE 


home 


Returns the input cursor to the begiiming of 
the form. Sets the de st i nat i on path 
register to /BEGIN. 


OlOF 
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Table V-6-4. Control Keys (cont.) 


Mnemonic Name 


Function 


Value (hex) 


insert.space 


bserts a blank space at the cursor position. 
In a date field, affects only the part of the 
date at the cursor position. 


0110 


inseit_overwrite 


Switches between insert and overwrite 
mode. In insert mode, existing characters 
move right to make room for new charac- 
ters. In overwrite mode, existing characters 
are replaced by new characters that are input 
in their position. 


0111 


next 


When the cursor is in a screen field or 
overlaid enumeration, skips to the next 
screen field, enumeration or to the end of the 
form. When the cursor is in a scattered 
enumeration, advances the cunor to the next 
enumeration element When the cursor is in 
a part of a date field, advances the cursor to 
the next part of the date field. 


0112 


next_with_clear 


Deletes the rest of the current screen field 
starting at the current cursor position (does 
nothing in an overlaid enumeration), then 
skips to the next screen field, or enumeration 
or to the end of the form. When the cursor 
is in a scattered enumeration, skips to the 
next dement of the enumeration. 


0113 


previous 


Moves the cursor to the beginning of the 
previous screen field. Sets the 
destination path register to the last 
touched screen fidd. When the cursor is in 
an overlaid enumeration, skips to the pre- 
vious screen field or enumeration. When the 
cursor is in a scattered enumeration, skips to 
the previous enumeration element. When 
the cursor is in a date field, moves the cursor 
to the previous part of the date field. 


0114 


refresh 


Refreshes (redisplays) the form image. 


0115 


reset 


Resets the form to its defined initial state, 
then restarts form entry at the first field. 


0116 


restore 


Restores the previous value of a field. 


0117 


button_l_released 


The first mouse button has been released. 


0118 


buttoa_2_released 


The second mouse button has been rdeased. 


0119 


button_3_released 


The third mouse button has been rdeased. 


OllA 


batton_4_released 


The fourth mouse button has been released. 


OllB 


battoD_5_released 


The first mouse button has been released. 


one 


sdectjocal 


Selects and desdects the vdue of option 
screen fields, displays the next dement in an 
overlaid enumeration and selects the current 
element of a scattered enumeraticm. 


OllD 


maiu_item_picked 


Indicates that a menu item was selected. 


OllE 


up 


Moves the cursor to the previous line in a 
multiple-line screen field. 


OllF 
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Table V-6-5. Application Keys 



Mnemonic Name 


Function 


Value (liex) 


U 


Application key 1. 


0200 


f-2 


Application key 2. 


0201 


u 


Af^licaUon key 3. 


0202 


f_4 


Application key 4. 


0203 


fj 


Application key 5. 


0204 


f_6 


Application key 6. 


0205 


f_7 


Application key 7. 


0206 


f_8 


Application key 8. 


0207 


f_9 


Applicati<»i key 9. 


0208 


f_10 


Application key 10. 


0209 


Ui 


Application key 1 1 . 


020A 


U2 


Applicaticm key 12. 


020B 


U3 


Application key 13. 


020C 


f_14 


Application key 14. 


020D 


U5 


Application key 15. 


020E 


U6 


Application key 16. 


020F 


f_17 


Application key 17. 


0210 


f_18 


Application key 18. 


0211 


f_19 


Application key 19. 


0212 


f_20 


Application key 20. 


0213 
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Table V-6-6. Information Keys 



Mnemonic Name 


Function 


Value (hex) 


button_l_pressed 


The first mouse button been pressed. 


0300 


button_2_pressed 


The second mouse button been pressed. 


0301 


button_3_pressed 


The third mouse button been pressed. 


0302 


button_4_pressed 


The fourth mouse button been pressed. 


0303 


button_5_pressed 


The five mouse button been pressed. 


0304 


input_focus_gained 


The window containing the form gained 
the input focus. 


0305 


input_focus_lost 


The window containing the form lost 
the input focus. 


0306 


oveilap_changed 


The visibility of the window containing 
the form changed. 


0307 


size_changed 


The size of the window containing the 
form changed. 


0308 


view_changed 


The position of the view of the fomi 
changed. 


0309 


position.changed 


The position of the window containing 
the form changed. 


030A 


scroll_requested 


Kind of scrolling requested: panning, 
bar, or dragging. 


030B 


user_defined_event 


A user-defined event 


030C 



By default, control keys are effective over an entire forni. They enable a user to trigger 
commonly used functions. The fomi programmer can disable control keys or give them other 
functions by catching them with a key catcher. 



V-6.17 Key Lists 



A key list contains names of printable and symbolic keys which are to be captured by the 
associated key catcher. Key lists can be created and modified with the form editor. 



V-6.18 Form Name Environments 

The name of a form element is called a basename. A basename is represented by a string of 
ASCn characters. To address all elements of a form, form service distinguishes between three 
name environments within a form: 

Form name environment - Names of all elements of a form with the exception of those con- 
tained in a group or subform of the form. 

Subform name environment - Names of all elements of a simple or group subform with the 
exception of those contained in a subform of that subform. 

Form global name environment - Names of all elements of the form including those contained 
in subforms. 

The names of the elements of a form or subform must be unique within the name environment 
of the form or subform. 

Instances of group subforms are named by the basename of the group followed by the number 
of the instance (index) in parentheses. 
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To address elements within subfonns, a form network pathname is constructed of one or more 
basenames or indexed basenames separated by a "/" (slash). For example, 
/group_3 (2 ) /screen_f ield_a is the form network pathname for screen_f ield_a 
of the second instance of group_3 of the form. 

An absolute pathname starts with a "/", and is evaluated starting with the name environment of 
the form. The simplest absolute pathname is the slash by itself that addresses the name en- 
vironment of the form. 

A relative pathname is any pathname that does not start with a slash, and is evaluated from the 
name environment of the currently executing subform or group instance, or from the form 
name environment if no subform or group instance is executing. 

The pathname "." (dot) represents the name environment of the form, subform or group in- 
stance currently executing. Similarly, the pathname ".." represents \he parent subform or 
group instance of the current subform or group instance, or the form if there is no parent 
subform or group instance. 

When no pathname (null string) is specified, the present form element is considered to be 
contained in the name environment of the subform or group instance currently executing, or if 
there is none, it is considered to be in the form name environment 



V-6.19 Execution Paths 

Execution of a form follows a path or a network of paths composed of the following elements: 

• Screen fields 

• Processing routines 

• Subforms 

• Groups 

• Fictive, predefined path elements: begin and end. 

BEGIN is the path element of a network, subform, or group that has no predecessor. END is 
the path element of a network, subfomi, or group that has no successor. Processing routines 
are the only path elements which may have more than one successor. A form may contain 
form elements which are not included in the execution network (texts, piles, subroutine inter- 
faces, data fields, key catcher caUs and key lists). Screen fields and subforms may be included 
in the network of paths; process routine caUs must be included. 

The path elements are executed in an order that is determined by: 

• the network of paths, and 

• the contents of the path registers. 

destination and next_path_element are predefined path registers that contain an 
arbitrarily selected path element and the normal successor to the current path element, respec- 
tively. They may be used by an application program, processing routines, and key catchers to 
influence the order in which path elements are executed. 

destination denotes a target path element to which execution will proceed. 
next_path_element contains the next path element to be executed. Normally, execution 
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will be permitted to follow the network as defined. However, conditions arise in which execu- 
tion must deviate from the defined path such as when infonnation entered into a screen field 
fails to pass a validation test and execution is returned to the cunent path element (screen field) 
for re-entry of the data. 

Execution begins with the current element, the first path element or the next path element 
depending on the following possible values of destination: 

• Ifdestination denotes a successor, execution proceeds from the current element to the 
destination element. 

• If destination denotes a predecessor, execution begins with the first path element of 
the form and proceeds until the destination is reached. 

• If de s t i na t i on is empty, execution proceeds with the next path element. 

V-6.19.1 Explicit l\/lodification of the Path Registers 

destination is explicitly set by an application program, a processing routine or a key 
catcher by calling Form_Handler . Set_destinat ion. 

next_path_element can only be modified with processing routines. The purpose of this 
register is to enable a processing routine to select one of its direct successor path elements. 
Selection of a successor is required if the routine has more than one successor. 

V-6.19.2 Implicit Modification of the Path Registers 

destination is implicitly set to empty if: 

• The target path element is reached. 

• The target path element cannot be reached. 

• A screen field which requires input would have been skipped. 

ne xt^pat h_e 1 emen t is implicitly set if: 

• The most recently processed path element has a single successor, then 
next_path_element is set to the name of the successor. 

• destination is set to a predecessor, then next_path_element is set to BEGIN. 

V-6.20 Messages and Help Information 

Local help information may be optionally assigned to screen fields and enumerations. The 
form developer must specify the name of a message and the name of the message file that 
contains the help infonnation. The message and the message file need not be available when 
the form is created but must exist by the time the form is executed. Local help messages can 
be accessed during execution by pressing the <help> key. Infonnation relating to the entire 
form can be accessed during execution by pressing the <globaI help> key. 

Mes sage_Adm calls are used to define and store help information. Infonnation messages are 
displayed on the standard message device. See the BUM™ Command and Message Guide for 
additional information on messages. 
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V-6.21 Window Management 

The window in which the fonn is displayed must have a frame buffer that is large enough to 
display the form with its current contents, otherwise Form_Handler . Get and 
Form_Handler . Put calls will fail. The size of the frame buffer limits the expansion of 
forms with variable size form elements. 

V-6.22 Summary 

• The form service builds upon the concept of a paper form to provide interactive forms 
capabilities on a terminal. 

• A form can be created with the form editor or the create . form utility. 

• A form may consist of the following/orm elements: 

- Texts 

- Screen fields 

- Enumerations 

- Data fields 

- Subforms 

- Groups 

- Piles 

- Subprogram interfaces 

- Processing routines 

- Key catchers 

- Key lists. 

• Variable length alphanumeric screen fields and the screen elements containing them can 
expand to accommodate data being entered into the field. 

• Execution of a form will follow a path or a network of paths composed of the following 
elements: 

- Screen fields 

- Processing routines 

- Subforms 

- Groups 

- Fictive, predefined path elements: BEGIN and END. 

• The path elements are executed in an order that is determined by the network of paths and 
the contents of the path registers (destination and next_path_element). 
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This chapter describes how to use the procedural interface of the form service to control and 
modify forms before and during their execution. You should read V-5.3 before reading this 
chapter. 

Packages Required: 

Form_Def s Defines types and constants used by the Form_Handler package. 

Form_Handler Provides calls to process, control, and change forms. 

V-7.1 Creating Executable Forms 

Developing an executable form involves: 

• Designing a form 

• Generating a form description with the form editor (edit . form) or create . form 

• Creating and binding a message file 

• Writing an application to execute a form 

• Writing processing routines, key catchers and key lists, as needed 

• Testing the form with the application. 

The following procedure is recommended for accomplishing the above steps. 

Step 1 - Design the Form 

Determine the primary design considerations related to the physical layout and the logic con- 
trolling the execution of the form. These considerations may include: 

• Names and locations of sheet elements 

• Specifications for subforms, groups and piles 

• The logic defining the networic of paths 

• Specifications for key catcher regions 

• Functional descriptions of processing routines and key catchers including parameter 
specifications and Form_Handler calls. 

If the form to be designed is based on a record description and can be executed sequentially 
without requiring any logic decision, no path logic considerations need be determined. The 
form editor provides a default path network, create . form also automatically provides a 
rudimentary, sequential, nonbranching path to the form. 

Step 2 - Create the Form 

Use the form editor, create . form or the DDef procedural interface to create a form 
description. 

Step 3 - Test the Form 

Use test . form to test and debug the execution logic, the validity of processing routine and 
key catcher calls, and the validity of the contents of fields. 

Step 4 - Create a Message File 

Use manage .messages to create a message file for the application program. This file can 
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be used for local and global help messages triggered by the <help> key, and for messages 
generated by processing routines and key catchers. 

Step 5 - Bind the Message File 

For a stable set of forms, use install . outside_environment to bind the message file 
to the application program. (More volatile form applications may handle messages directly.) 

Step 6 - Write an Application Program 

A form is caUed by a high-level language program. 

Step 7 - Write Subroutines, Translation Tables and Key Lists 

Write processing routines and key catchers referenced in the form design. Use the translation 
table editor to create any translation tables needed in addition to the default translation table 
provided by the Form_Handler. (Translation tables map the ASQI sequences generated by 
input devices to symbolic keys.) 

Step 8 - Test the Form with the Application 

Use test . form to again test the form. Include desired debug features in the application 
program, processing routines, and key catchers. 

Step 9 - Create a Window 

To execute a form, this program must create a window for the form to execute within. A 
window must be provided before a form can be opened. Therefore, the application program 
calls Window_Services . Create_window or 
Window_Services . Ops . Create_window to provide a window for the form. 



V-7.2 Command Language Variables 



The following list contains the names, descriptions, types, and initial values of the CL 
(Command Language) variables used by the form service. CL variables affect the appearance 

TM 

and performance ofthe form editor and Form_Handler. See the BUN Systems Form 
Editor Guide for instructions on setting a screen field so that it can accept a CL variable as 
input and for a description of the CL variables used to make general adjustments to the form 
editor. The scope of each ofthe variables may be: 

H - Evaluated by the Form_Handler. 

E - Evaluated by the fonn editor. The variables are valid 
throughout the editing session or are relavant only in the 
initialization phase. 

D - Evaluated by the form editor. These variables provide 
default values for editor adjustments which may be changed 
during an editing session. 

See V-1 for a general discussion of CL variables. 

f orm. decimal_character 

Character which will be displayed and accepted as the decimal symbol. 
The possible values are Form_Defs .point and Form_Def s . comma. 

Scope: H, D 
Type: string 
Initial Value: "." 

form . insert_mode 

Input mode set when the user starts to edit a new form. If true, mode is 

Programming with Forms V-7-3 



insert, else the mode is overwrite. The value of this variable can be 
toggled with the <insert_overwrite> key. 

Scope: H, E 
Type: boolean 
Initial Value: true (insert) ) 

form . visual_bell 

Indicates whether signals sent to the terminal will be visual or audible. If 
true, signal is visual, else the signal is audible. 

Scope: H, D 
Type: boolean 
Initial Value: false (audible) 

form . keyjmap Symbolic name of the translation table that is used by the 

Form_Handler to translate incoming characters into symbolic keys. If 
null, a standard, internal translation table is used. 

Scope: H 
Type: string 
Initial Value: null 

form.expansion_step 

Contains the number of characters by which a variable-length, al- 
phanumeric field will expand horizontally when the present size is ex- 
ceeded by data being entered into the field. 

Scope: H, E 
Type: integer 
Initial Value: 1 

form . escape_character 

The character which is used as the escape symbol in a format string. See 

TM 

the BUN Systems Form Editor Guide for information concerning format- 
ting screen fields. 

Scope: H, D 
Type: string 
Initial Value: \ (backslash) 

form . editor_key_map 

Symbolic name of the translation table used by the form editor to translate 
incoming characters into symbolic keys. If null, a standard, internal trans- 
lation table is used. 

Scope: E 
Type: string 
Initial Value: null string 

form . window_position_line 

Line number of the upper-left position of the Info window. The upper line 
of the Main window depends on the CL variable 
form . inf o_window_lines and the upper line of the Message win- 
dow is likewise dependent on the values of 
form, inf o_window_lines plus form.main_window_lines. 

Scope : E 
Type: integer 
Initial Value: 1 

f orm. window_position_col\imn 

Column number of the upper-left position of the Info window. 

Scope: E 
Type: integer 
Initial Value: 1 
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form . window_columns 

Width in columns of the three editing windows. 

Scope: E 
Type: integer 
Initial Value: 80 

f orm. inf o_window_lines 

Number of lines in the Info window. 

Scope: E 
Type: integer 
Initial Value: 10 

f orm . niain_window_lines 

Number of lines in the Main window. 

Scope : E 
Type: integer 
Initial Value: 10 

form.message_window_lines 

Number of lines in the Message window. 

Scope : D 
Type: integer 
Initial Value: 1 

form . pop_up_message_window 

Determines whether the Message window wiU open and close upon the 
receipt of a message or stay open. If true, a Message window is opened 
each time a message is to be displayed, and closed when input is entered 
into any of the editor windows. 

Scope : D 
Type: boolean 
Initial Value: false 

form.editor_adjustments 

Symbolic name of the form editor adjustments object. This object contains 
adjustments that affect the appearance and operation of the form editor. 
Adjustments may be made and saved with the form editor. If this string is 
null, default adjustments are used. 

Scope : E 
Type : string 
Initial Value: null string 



V-7.3 Form Utilities 



The following utilities are provided to automatically create a simple, standard form, to test a 
form, and to map symbolic keys to specific terminsis: 

• test. form 

• create. form 

• Translation tables editor. 

test . form interactively tests and debugs forms. It provides the following functions: 

• Identifies any missing processing routines or key catchers. 

• Provides information about fields. 
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• Displays and permits changing the contents of fields. 

test . form displays and executes a form. When during execution of the fonn a processing 
routine or key catcher is found to be missing or a field's contents are invalid, execution is 
suspended and a message is displayed. The form tester may change or change the contents of 
fields. 

The form tester may change the value of the predefined path registers destination and 
next_j5ath_element while the form is executing. It is not possible, however, to modify 
the path. 

When form execution is terminated, status information for the form displays. 

create . form automatically generates the most simple, default form design based upon the 
description of the associated data record. This utility is called with the name of a record 
description and the name to be given the new form. It can be used with the form editor to 
customize a form. 



V-7.4 Editing Translation Tables 

Translation tables map the ASCII sequences generated by input devices to symbolic keys by 
associating a raw key (a sequence of keystrokes) with a symbolic key. Translation tables can 
be created and edited with the translation tables editor]. A translation table is required for each 
terminal on which a fonn will be executed thus providing terminal independence. 

One default translation table is always associated with the Form_Handler. See 
Form_Def s for a description of the elements of this default translation table. 

V-7.5 Techniques 

After reading this section, you will be able to: 

• Open, execute, and close a form 

• Insert data into a form and retrieve data from a form 

• Alter the order of execution 

• Add and remove group instances before and during execution of a form 

• Modify the appearance of form elements 

• Retrieve information about the state of a form. 

The sample code segments are excerpted from the Inventory_Forms_Ex example pack- 
age. 

V-7.5.1 Opening and Closing Forms 



V-7-6 Programming with Forms 



rKliLlJYUINAKY 



Calls Used: 

Form_Handler .Open_f orm 
Opens a form. 

Form_Handler . Close_f orm 
Qoses a fomi. 



The application program opens the fonn with Open_f orm. Then the fonn can be activated for 
dialogue. The status of the fonn is set to initialized, and defaults arc assigned to the 
fonn element values. Close_f orm deallocates the opened fonn. The following excerpt 
shows a fonn being opened and closed: 

40 opened_form: Form_Defs .opened_forin_AD; 

44 opened_form := Form_Handler .Open_form( 

45 DDef => DDef_from_untyped( 

4 6 Directory_Mgt .Retrieve { 

47 name => form_pathname) ) ) ; 

[form is executed] 

191 Form_Handler.Close_form( 

192 opened form a => opened form) ; 
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Calls Used: 



Form_Handler . Get 

Executes a forni (displays the fomi and accepts input from the user). 

Form_Handler . Compute 

Executes a fomi without displaying the forni or requiring input 

Form_Handler .Put 

Displays a form without executing it. 



When Get is called, the fonn sheet is displayed and the form awaits user input The opened 
fonn must have status initialized, suspended, or input_required. This is the 
most common method for executing a forni as shown in the following example code: 

236 

237 form_status := Form_Handler .Get ( 

238 opened_form_a => opened_form, 

239 opened_window_a => Inventory_Windows . 

240 main_window) ; 

Compute executes a fomi similar to Get but does not display the fonn or require input. 
Execution is suspended if input is required by a field. This call can be used to validate screen 
field values which receive their values from processing routines rather than user input. 

Put displays a fonn while refusing user input. It is commonly used for displaying foraas on 
output-only devices such as printers, or for displaying forms on tenninals when no input is 
required. 
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V-7.5.3 Setting and Resetting the Initial State of a Form 

Calls Used: 

Form_Handler . Set_initial_state 

Sets the status of the form to initialized and marics the current con- 
tents of the screen fields and enumerations as initial values. 

Form_Handler .Reset_f orm 

Resets a form to the same state as immediately after its last initialization. 

Form_Handler . Clear 

Qears a form from the screen. 



Set_initial_state sets the status of the form to initialized and sets the current 
contents of the fields, the current number of instances of groups, and the current display at- 
tributes of fields and texts at their initial values. 

Initial values arc particularly significant under the following conditions: 

• Ifthe<reset> key is entered (or Re s e t_f o rm is called) while the form is executing, 
the fields, group instances, and display attributes of fields and texts are reset to their respec- 
tive initial values. 

• If there is more than one data entry sequence defined by the network of paths, 
Form_Handler uses the initial values as necessary to keep the form consistent with it- 
self. For example, the form user may enter data into all tiie fields of a path, then use 
symbolic keys to return to an earlier field in the path and change its value. If the user then 
causes execution to proceed along another path, Forrn_Handler implicitiy resets the con- 
tents of the fields, group instances, and display attributes of fields and text in die first path 
to their initial values. 

Reset_f orm returns a form to the state immediately after its last initialization. The last 
initialization may have been performed implicitiy with Open_f orm or explicitiy with 
Set_initial_state. See the Interrupting Execution section for an example of 
the use of this call. 

Clear removes a form sheet from the window usually in preparation for a new operation. 
The status of the form remains unchanged. 

702 

703 Form_Handler. Clear { 

704 opened_forin_a => opened_form) ; 
705 

706 Form_Handler.Close_form( 

707 opened_form_a => opened_form) ; 

V-7.5.4 Inserting, Storing, and Deleting the Contents of Screen and Data 
Fields 
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Calls Used: 

Form_Handler . Store_value 

Sets the value of a screen field, data field or enumeration element. 

Form_Handler . Fetch_value 

Retrieves the value entered into a screen field, data field or enimieration 
element. 

Form_Handler .Delete_value 

Empties a screen field, data field, or enumeration. 



Store_value assigns a value to a screen field, data field, or enumeration. If the form is 
displayed, the new values of screen fields appear on the screen. 

276 Forin_Handler .Store_value ( 

277 opened_form_a => opened_form, 

278 element => desc_field, 

279 subunit => System_Def s .null_text, 

280 — added subunit; value correct? 

281 value_buffer_VA => 

282 parts_record.desc' address, 

283 value_length => 

284 parts_record.desc' size/8, 

285 value_t => 

286 Data_Definition_Mgt .t_string) ; 

Fetch_value retrieves the value entered into a screen field, data field or enumeration ele- 
ment. 

249 

250 Form_Handler .Fetch_value ( 

251 opened_form_a => opened_form, 

252 element => part_ID_f ield, 

253 subunit => System_Defs .null_text, 

254 — added subunit; value correct? 

255 value_buffer_VA => part_ID' address, 

256 value_length => part_ID' size/8, 

257 value_t => 

258 Data_Definition_Mgt .t_string, 

259 element_value_length => length, 

260 empty => empty) ; 
261 

262 if empty then 

263 — null part_ID; return to menu 
264 

Delete_value removes the value of a screen field, data field, enumeration which are con- 
tained in an associated record description, and which have a representation for the null value 
defined. 

V-7.5.5 Controlling the Execution Path 

A form will execute according to the networic of paths defined when the form is created or 
modified. This network of paths may contain branches controlled by processing routines 
which determine the next executable element depending upon the value of entered or cal- 
culated data. Explicit control over the execution path is provided by Set_destinat ion. 
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Calls Used: 

Form_Handler . Set_destination 

Stores a path element name in the destination path register. 



Set_dest inat ion stores a path element name in the destination path register. If the 
path element is a successor of the current path element, all path elements up to the specified 
path element are executed. If the specified path element is a predecessor of the current path 
element, execution of the form starts again with the first path element of the form and con- 
tinues to the specified element. A boolean may be set to indicate whether processing routines 
are to be executed. 

The next_path_element path register, unlike destination, cannot be modified 
directly by the application or by Form_Handler but can be modified by a processing 
routme. 

V-7.5.6 Processing Routines and Key Catchers 

A subroutine (processing routine or key catcher) is added to a form with the form editor. The 
form editor incorporates a subroutine into a form by specifying a subprogram interface for the 
subroutine. To generate the subprogram interface, the editor requires: 

• Programming language 

• Name of the subprogram interface 

• in parameters 

• out parameters 

• Link option. 

V-7.5.7 Defining a Processing Routine 

A processing routine is added to a form by defining the following items with the form editor. 

• Name of the processing routine call 

• Subprogram interface 

• Name of the referenced form element 

• in parameters 

• out parameters. 

next_path_element is an out parameter that specifies the name of a path element of the 
currently executed subform or form, and is stored in the next _path_element predefined 
path register. A processing routine with more than one direct successor must have this 
parameter. Processing routines with only one successor must not specify this parameter. 

terminal_input, an optional in parameter, has an actual value of a byte string that is 
interpreted as a sequence of symbolic keys and inserted into the stream of input keys replacing 
the last key processed. This parameter references an internal queue where symbolic keys 
arriving from the keyboard are stored. A processing routine can write directly into this queue 
to simulate user input. 
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When a processing routine call is reached during the execution of a fonn, Form_Handler 
caUs the processing routine specified by the corresponding subprogram interface. The same 
processing routine can be called from several locations within a form's network of paths. 

V-7.5.8 Defining a Key Catclier 

A key catcher is added to a form in the same way as a processing routine except for the 
additional following items: 

• Key list 

• Region of effectiveness. 

A key list is created by the form editor and contains the keys to be caught by a key catcher. 
The region of effectiveness is a screen field, enumeration, subfonn or group to which a key 
catcher is assigned. 

trigger_key is an in parameter which receives the value of the symbolic key that triggers 
the key catcher. It references a predefined Form_Handler register. This register enables the 
key catcher to inquire as to which key contained in the associated key list caused the call. 

V-7.5.9 Interrupting Execution 

Besides altering the execution path, the application may also stop execution. With the next 
two calls, execution can be arbitrarily terminated, or halted. These calls can only be made by 
processing routines or key catchers. When the processing routine or key catcher returns, the 
application again gains control. 

Form_Handler . Abort_f orm 

Aborts execution of a form. 

Form_Handler . Suspend_f orm 

Suspends execution of a form. 



Abort_f orm halts and exits the execution of a form. All data entered during the current 
execution of the form is lost. This call can be made indirectly by pressing the <abort> key. 

Suspend_f orm suspends execution of a form without losing the currently entered data and 
awaits a status change before execution is resumed. Suspend_f orm can only be called by a 
processing routine or a key catcher. The execution of the form is suspended when the calling 
processing routine or key catcher returns, and the application gains control. The apphcation 
must call Get to resume execution of the form. 

V-7.5.10 Adding and Removing Group Instances 

The number of group instances required for any given execution of the form can vary accord- 
ing to the value of data entered. Therefore, the next two calls provide a means for increasing 
and decreasing the number of instances of a group prior to or during the execution of a form. 
When a form is created, a default number of instances is assigned to each group. This number 
may be changed dynamically with Create_group_instance and 
Remove_group_instance. 
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Calls Used: 

Form_Handler . Create_group_instance 
Creates group instances. 

Form_Handler . Remove_group_instance 
Removes group instances. 



The following code shows creating a group instance. 

808 begin 

809 — Add another instance of the supplier ID group. 

810 Form_Handler.Create_group_instances ( 

811 opened_form_a => opened_form, 

812 group => suppliers_field, 

813 number_of_instances => 1) ; 
814 

815 exception 

816 when Forin_Handler .maximum_number_reached => null; 
817 

818 end; 

In this example, the Supplier ID is a group of three instances. The first instance is dis- 
played when the field is executed (default instances = 1). Entering a supplier ID and pressing 
the <return> key advances the cursor to the next screen field. If this part ID has a second 
supplier, the user presses the <next> key to display a second group instance. After the third 
group instance is displayed, the form service knows that this group has a maximum of three 
instances and will continue with the next path element regardless of the key pressed. This code 
segment is called by a key catcher which is triggered by the <next> key. 

V-7.5.1 1 Modifying the Appearance of a Form 

Screen fields, enumerations and text can be given the following display attributes: 

• inverse video 

• underline 

• half-bright 

• blinking 

• blankfill 

• text color (color terminal only) 

• font index (graphics terminal only) 

• concealment (contents of a field are not displayed). 

Any of these attributes may be changed, or reset to their initial values. 

Calls Used: 

Form_Handler . Change_display_attributes 

Changes the display attributes of a screen field, enumeration, or text. 

Form_Handler . Restore_display_attributes 

Restores the display attributes of a screen field, enumeration, or text. 
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Display attributes include: 

• inverse video 

• underlining 

• half-bright 

• blinking 

• blank fiU 

• font index 

• concealing (not displaying) the contents of a field. 

An example use of these two calls is to blink a field's contents to alert the user that the entered 
data is erroneous and must be reentered. The field is restored to its original attributes after the 
user enters a valid value. 

V-7.5.12 Inquiring About an Element, Form Sheet, and Form Status 

An application can more effectively control the execution of a fonn when it is able to access 
the identity and current state of form elements. The availability of information about the form 
sheet during execution ensures that device-dependent considerations stay transparent to the 
user. Form status and other current state information gives a valuable snapshot of the execut- 
ing form. AU this information is made available to the application by the following caUs. 

Calls Used: 

Forrn_Handler . Get_current_nviinber_of_group_instances 
Gets the current number of instances of a group. 

Form_Handler . Get_current_jpath_element 

Gets the name and type of the path element currently being executed. 

Form_Handler . Get_current_subunit 

Gets the pathname of the current subunit. 

Form_Handler . Get_element_inf o 

Returns information about an element. 

Form_Handler . Get_index_sequence_of _current_subunit 

Gets the index of each subunit (group instances and subforms) comprising 
the current subunit 

Form_Handler . Get_last_edited_sheet_element 

Gets the pathname of the last edited screen field or enumeration. 

Form_Handler . Last_input_event 

Gets information about the last input event. 

Form_Handler . Get_selected_sheet_element 

Gets information about the sheet element selected by the last mouse event 

Form_Handler . Get_sheet_inf o 

Returns information about the currently displayed form sheet. 

Form_Handler . Get_status_inf o 

Returns information about the status of a form. 
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Get_element_inf o returns the type of the element and whether the contents of the ele- 
ment have been changed since the last initialization. 

Get_sheet_inf o returns size information about the currently displayed form sheet and 
whether it is designed to be displayed on a character or graphics terminal. 

Get_selected_sheet_element returns similar information as Get_element_inf o 
except that the element is selected by a mouse event. This call is used by key catchers which 
catch mouse events. 

This information is typically evaluated by the application program when the execution of a 
form is suspended or aborted. 

V-7.5.13 Inquiring About the Last Edited Sheet Element and Input Event 

These calls retum information identifying a previous action. 

Calls Used: 

Form_Handler . Get__last_edited_sheet_element 

Provides the form network pathname of the screen field or enumeration 
last edited. 

Form_Handler . Get_last_input_event 

Returns the type of the last input event. 



Get_last_edited_sheet_element returns the form network pathname of the last 
screen field or enumeration that was edited. This call is commonly used by processing 
routines to aid in determining which successor to choose as the next path element. 

Get_last_input_event returns the type of the last input event. This call is used 
similarly to ge t_l a s t_e di t e d_s h e e t_e 1 erne n t . 

V-7.6 Summary 

• Form_Handler enables an application to dynamically control a form. 

• After a form has been created, it can be executed and controlled by Form_Handler calls 
which perform the following functions: 

- Open and close a form 

- Execute a form 

- Insert and store data 

- Modify the order of execution 

- Add and remove group instances 

- Modify the appearance of the form 

- Inquire about the state of the form. 

• Developing an executable form involves: 
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- Designing a form 

- Generating a fonn description 

- Creating and binding a message file 

- Writing an application to execute the fonn 

- Writing processing routines, key catchers and key lists, as needed 

- Testing the form with the application. 

• The following steps comprise a recommended procedure for accomplishing these tasks: 

Step 1 - Design a Form Layout. 

Step 2 - Create the Form. 

Step 3 - Test the Form. 

Step 4 - Create a Message File. 

Step 5 - Bind the Message File. 

Step 6 - Write an Application Program. 

Step 7 - Write Subroutines, Translation Tables and Key Lists. 

Step 8 - Test the Form with the Application. 

Step 9 - Create a Window. 

• A screen field can be set to accept a CL variable as input 

• The following utilities are provided to automatically create a simple, standard form, to test 
a form and to map symbolic keys to specific terminals: 

- test. form 

- create . form 

- Translation tables editor. 
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V-8.1 Concepts 

This chapter discusses the ways to create and modify a report description and print a report:. 

Packages Used: 

Report_Handler 

Provides calls for initializing and printing a report. 



A report is a printed or displayed document containing labelled data, often presented in hierar- 
chical groups with subtotals and totals. A simple report is shown in Figure V-8-1. 





INVENTORY REPORT 






Part ID 


Description 


Location 


Unit 


1234567 


wiring harness 


13-B27 


each 


3512734 


1/2" aluminum conduit 


02-F12 


feet 


4766117 


5/16" hex carriage bolt 


07-A02 


lb 


7689482 


flexible control cable 


06-C13 


inch 



Figure V-8-1. Sample Report 



V-8.1. 1 Report Characteristics 

A report is made up of various combinations of the following report parts: 

• Report heading 

• Report footing 

• Page heading 

• Page footing 

• Control group footing 

• Control group heading 

• Record print layout. 

A typical report consists of one or more pages of data, a report heading, and a report footing 
(see Figure V-8-2). 
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Figure V-8-2. Page Series of a Report 



The report heading prints on a separate page and may contain explanatory information similar 
to the title of a book or the burst page of a print job. The report footing may print on the last 
page or a separate page and can contain summary statistical information pertaining to the 
report Both are optional. 

Data appears on the report pages other than the report heading and footing pages. The layout 
of a page is defined by the page body area shown in Figure V-8-3. 
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Figure V-8-3. Parts of a Report Page 



hpage header typically contains the date, page number, and headings for the columns of data. 
The page footer typically contains statistics or is empty. Both are optional. 

The record print layout defines how the records are to be printed. This layout includes infor- 
mation about: 

• the record fields selected for printing 

• additional, explanatory information 

• user-defined expressions 

• position, display attributes, and formatting of the record fields. 

The page body area contains one or more kinds of items defined by the record print layout: 

• A data corresponds to a field of the record from which the report is derived. It contains a 
reference to this field and all information about the layout of the data. When the detail is 
printed, the content of the corresponding record field is printed. 

• Computed data contains a mathematical expression. The expression may contain 
references to data in the same report part or in another report part. It contains all infor- 
mation about the layout of the data. When the report is printed, the expression is calculated 
and the result of the calculation is printed. 

• A text represents an explanatory text string. 

The data in the page body area may be an unstructured stream of records or may be structured 
in groups of records framed by intermediate headings and footings called control groups. The 
records within control groups have in common a particular field which contains the same 
value. 
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Figure V-8-4 illustrates control groups in three consecutive pages of a report. Two control 
groups are defined. Control group 2 is nested within control group 1. The 
dominant/subdominant relationship of the control groups defines tiie control hierarchy. 
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Control Group Footing 2 


Control Group Heeding 2 
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Control Group Footing 2 
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Control Group Footing 1 
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Figure V-8-4. Report With Nested Control Groups 



V-8.1.2 Control Groups 



Records printed in the page body area can be grouped into control groups. If a stream of 
records contain groups of records having at least one field with the same value, this collection 
of records can be printed as a group. The field with the common value can be designated as a 
control group field. 

Control groups may be nested. When nested, control groups define a hierarchical structure 
called the control group hierarchy that controls the sequence of printing the records. 

Each time a record of the file is read, the contents of all control fields are evaluated. The 
change of the value of a record field designated as a control field causes a control break. On a 
control break, printing is suspended until the following actions have been performed: 

• All control group footings are printed beginning from the lowest level of control group 
hierarchy up to tiie level associated with the highest level of the control field which caused 
the control break. 
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• All control group headings arc printed beginning from the level associated with the highest 
level of the control field which caused a control break down to the lowest level. 



Figure V-8-5 shows a report with control breaks on the location field of the Parts Master 
File record of the Inventory Program example. The Cost column is defined as computed data 
which is the product of qty_on_hand (not reported) and ave_unit_cost (not reported). 



Date: 12/31/87 I 


nventory Location Report 




Page: 1 


Location 


Part ID 


Description 


Unit 


Cost 


02-F12 


3512734 


1/2" aluminum conduit 


feet 


121.98 




3571998 


5/8" aluminum conduit 


feet 


317.69 




3521195 


3/4" aluminum conduit 


feet 
Total: 


79.50 
519.17 


07-A02 


4766117 


5/16" hex bolt 


lb 


17.69 




4619984 


3/8" stove bolt 


lb 


37.55 




4722390 


1/2" crenellated nut 


lb 
Total: 


7.05 
62.26 






Grand 


Total: 


581.43 



Figure V-8-5. Report With Control Breaks 



V-8.1.3 Representation of Report Descriptions 

A report description is composed of report parts. Figure V-8-6 shows an example of the report 
parts that are combined in a report description. 
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Report 
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Page 
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Page 
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Print Layout 



kL'' 



Report 
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Figure V-8-6. Report Parts of a Report Description 



The report service requires a record DDef that describes the data to be printed. The record 
DDef can be created using Dat a_Def inition_Mgt , or an existing record DDef for a file 
can be used. 

V-8.1.4 Creating and Modifying a Report Description 

Three methods are available for creating and modifying report descriptions: interactively with 
edit . report, dynamically with create . report, and procedurally using 
Data_Def inition_Mgt. The report editor, edit . report, is the most commonly used 
method, create . report is the easiest method for generating a simple report. 
Data_Def inition_Mgt is the most fundamental and complex method and is primarily a 
tool for utility writers. 

Application programmers will normally use edit . report to create a report description. 
Report descriptions can also be created procedurally using Data_Def inition_Mgt, al- 
though this method requires a detailed understanding of DDefs. This low-level procedural 
interface is mainly of interest to implementors of utilities such as edit . report. 

The report editor, edit . report, is an interactive utility for creating and modifying report 
descriptions. Upon successful completion of a report design or update, the report editor 

TM 

generates a report description that can be used to print the report. See the BiiN Systems 
Reports Guide for detailed information on report editor. 
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create . report automatically creates the most simple, default report design based upon the 
description of an associated data record. See the BiiN^ Systems Reports Guide for instmctions 
on using this editor. The layout of a standard report page is shown in Figure V-8-7. 
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Figure V-8-7. Layout of a Standard Report Page 



The report parts for a stand^d report assume the following default properties: 

Record print layout The data of the record print layout is taken from the corresponding fields 
of the record. 

Within the page body area, the data is printed line by line (according to the 
records read) and positioned beneath the matching column. 

The width of a column is determined by the length of the name of the field 
in the heading and by the length of the field (by the format string for 
numeric fields), whichever is larger. The smaller one is centered within 
the column. 

Default formats for numeric and date data are shown in Table 4-1. 
Table V-8-1. Standard Report Default Formats 



Default Foimat 


Type 


-7.y.7'.7.7,7,77',7Q 


mt4 


-ZZ7y.ZZZZZ77,7,ZZZZZ7,9 


intS 


-9.9999999999E-99 


reals 


yyyy-mm-dd 


date 



Numeric fields are right-justified; byte string fields are left-justified. 

Control group hierarchy 

When the report is associated with a variant record, control hierarchies are 
defined by the standard layout for readability. 
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If the record description does not contain variant parts, no control group 
hierarchy is defined. 

Control group headings 

No control group heading is defined. 

Control group footings 

No control group footing is defined. 

Page heading The page heading prints the date on the left and the current page number 

on the right. A tabular heading line is printed in the third line of the 
heading. For variant records, the tabular heading line reflects the contents 
of the first record to print on any given page. 

Page footing The page footing is defined as a single, empty line. 

Report heading and footing 

The report heading and footing arc not defined. 

V-8.1 .5 Report CL Variables 

The following lists contains the names, descriptions, types, and initial values of the CL 
(Command Language) variables used by the report service. CL variables affect the appearance 
and performance of the report editor and report handler. See the BUN™ Systems Reports Guide 
for instructions on the use of CL variables. See V-1 for a general discussion of CL variables. 

The scope of a variable is defined as £ or D. E means that the variable is valid throughout the 
editor session or is only relevant in the initialization phase. D means that the variable provides 
default values for editor adjustments which may be changed during an editor session. 

Report Editor-Specific CL Variables 

report. edi to r__ke y_map 

Symbolic name of the translation table that is used by the report handler to translate incoming 

characters into symbolic keys. If null, a standard, internal translation table is used. 

Scope : E 
Type : string 
Initial Value: null string 

report .window_position_line 

Line number of the upper-left position of the Info window. The upper line of the Main win- 
dow depends on the CL variable report . inf o_window_lines and the upper line of the 
Message window is likewise dependent on the values of report . inf o_window_lines 
plus report .inain_window_lines. 

Scope : E 
Type: integer 
Initial Value: 1 

report .window_position_column 

Column number of the upper-left position of the Info window. 

Scope : E 
Type: integer 
Initial Value: 1 

report .window_coluinns 

Width in columns of the three editing windows. 

Scope: E 
Type : integer 
Initial Value: 80 
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report . inf o_window_lines 
Number of lines in the Info window. 

Scope : E 
Type : integer 
Initial Value: 10 

report .main_window_lines 
Number of lines in the Main window. 

Scope : E 
Type : integer 
Initial Value: 10 

report .message__window_lines 
Number of lines in the Message window. 

Scope : D 
Type : integer 
Initial Value: 1 

report .pop_up_message_window 

Determines whether the Message window will open and close upon the receipt of a message or 
stay open. If true, a Message window is opened each time a message is to be displayed, and 
closed when input is entered into any of the editor windows. 

Scope : D 
Type : boolean 
Initial Value: false 

report . editor_ad justments 

Symbolic name of the report editor adjustments object This object contains adjustments that 
affect the appearance and operation of the form editor. Adjustments may be made and saved 
with the fonn editor. If this string is null, default adjustments are used. 

Scope : E 
Type : string 
Initial Value: null string 

General CL Variables Used by the Report Editor 

form . decimal_character 

Character which wiU be displayed and accepted as the decimal symbol. The possible values 

are Form_Def s .point and Form_Def s . comma. 

Scope: D 
Type: string 
Initial Value: "." (point) 
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form . escape_character 

The character which is used as the escape symbol in a format string. See the BUN'" Systems 

Reports Guide for information concerning fonnatting screen fields. 

Scope: D 
Type: string 
Initial Value: \ (backslash) 

form . visual_bell 

Defines whether the editor user will be informed visually or audibly of incorrect input. If true, 

the signal is visual, else the signal is audible. 

Scope : D 
Type: boolean 
Initial Value: false (audible) 
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user .verbose 

Indicates whether status messages should be displayed. 

Scope : D 
Type : be 
Initial Value: false (not displayed) 



I Type : boolean 



user . language 

Defines whether the editor user will be informed visually or audibly of incorrect input. If true, 

the signal is visual, else the signal is audible. 

Scope : D 
Type : string 
Initial Value: null string 

msg . long_text 

Used by the message service to detennine whether the long or short version of a message is to 

be used. 

Scope: D 
Type : boolean 
Initial Value: false (short) 

V-8.1.6 Printing a Report From the Command Line 

print . file is a general purpose utility with which reports can be printed or displayed. It 
reads the input file and writes tiie report to a spool queue. See the BUN™ Systems 
Administrator's Guide for more information about this utility. 

V-8.2 Techniques 

After reading this section, you will be able to: 

• Print a report fiom your program 

• Optionally sort a file and print the sorted entries 

• Change global assignments. 

The examples used are excerpted from the Inventor y_Reports_Ex example listed in 
Appendix X-A. 

V-8.2.1 Printing a Report From Your Program 

Calls Used: 

Report_Handler . Initialize 

Initializes a report for printing. 

Report_Handler . Print 

Prints an initialized report. 



Initialization associates a report description with an input device opened for record stream 
input, and an output device opened for character display output to which the report is printed. 
Report Handler . Print prints an initialized report. 



Generating Reports V-8-11 



The entire input stream is printed in input order; that is, by record number for relative files or 

by index for indexed files. The input file may be the entire, original file associated with the 
report description or a subset of this file. 

If the file is an indexed file, a subset of the original file can be selected with 
Record_AM . Keyed_Ops caUs. If the report control hierarchy fields differ from the key 
fields of which the file index is composed, then Sort_Merge_Interf ace . Sort can be 
called to generate a record stream with the required record order. 

The following sample code demonstrates the use of Report_Handler .Print in which a 
range of records is printed in indexed order. 

76 local_parts_file: Device_Defs. device := 

77 Record_AM.Ops.Get_device_object { 

78 Inventory_Files.parts_f ile) ; 

79 — AD to parts file. 
80 

81 opened_local_parts_file : 

82 Device_Defs.opened_device; 

83 — AD to locally opened parts file. 
84 

85 part: System_Defs.text (4 ) := (4, 4, "part") ; 

86 — Parameter to "report_printing" message, 

87 — since this report is by "part". 
88 

89 begin 
90 

91 — Open parts file for reading, so no 

92 — concurrent updates will interfere: 
93 

94 opened_local_parts_file := Record_AM.Ops.Open ( 

95 dev => localj?arts_f ile, 

96 input_output => Device_Defs .input, 

97 allow => Device_Def s. readers ) ; 
98 

99 

100 — Open output device: 
101 

102 opened_output := Byte_Stream_AM.Open_by_name { 

103 name => 

104 output_dev_pathname, 

105 input_output => 

106 Device_Def s. output ) ; 
107 

108 

109 — Get report definition (DDef) : 

110 

111 report_DDef := DDef_from_untyped{ 

112 Directory_Mgt .Retrieve ( 

113 name => report_by_part_DDef_pathname) ) ; 

114 — Assume "Report_Handler . Is_report" . 
115 

116 

117 — Initialize report: 

118 

119 initialized_report := Report_Handler. Initialize ( 

120 description => report_DDef, 

121 input => opened_local_parts_f ile, 

122 output => opened_output) ; 
123 

124 

125 — Print report: 

126 

127 Report_Handler.Print { 

128 report => initialized_report) ; 
129 

130 
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131 — Display "report_printing" message: 
132 

133 Message_Services.Write_msg( 

134 msg_id => report_printing_code, 

135 paraml => Incident_Defs .message_parameter { 

136 typ => Incident_Defs.txt, 

137 len => part .length) ' { 

138 typ => Incident_Defs.txt, 

139 len => part. length, 

140 txt_val => part), 

141 param2 => Incident_Defs .message_parameter { 

142 typ => Incident_Defs.txt, 

143 len => output_dev_pathnaine. length) ' ( 

144 typ => Incident_Defs.txt, 

14 5 len => output_dev_pathname. length, 

146 txt_val => output_dev_pathname) , 

147 device => Inventory_Windows.message_window) ; 
148 

149 

150 — Close locally opened parts file: 

151 

152 Recor d_AM. Ops. Close ( 

153 opened_dev => opened_local_parts_file) ; 

The report service also implements record I/O as another method for printing reports. This 
method enables printing reports from applications written in languages such as COBOL that 
provide record I/O but do not support ADs. Using record I/O to print a report is similar to 
writing to a file. The application program opens a device specifying the report description. 
Each Insert caU supplies a record to the report service. The report is sent to the application 
program's current output device; that is, the standard output specified in the process globals. 

The report service allows report descriptions for files which contain variant records. 
V-8.2.2 Setting Global Assignments 

Calls Used: 

Report_Handler . Set_global_as signs 

Assigns the error handling controls for an initialized report. 



Several global properties may be set by report editor. Two of these, error decision and line 
end decision, may be changed with Set_global_as signs. 

The error decision defines the action to be taken when a numeric error (overflow, underflow, 
or division by zero) occurs during the evaluation of an arithmetic expression. Possible actions 
include: 

• Printing the error symbol (default is ?) instead of the erroneous value 

• Suspending the evaluation of the current item, and continuing printing with the next item 

• Terminating the report (closing output and returning). 

The line end decision defines the action to be taken when the width of the mounted sheet is too 
small for printing the report lines. Possible actions include: 



Printing the remaining characters on the next line 
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• Discarding the remaining characters 

• Terminating the report. 



V-8.3 Summary 



The report service and related utilities provide methods for creating and modifying a report 
description and for printing a report. 

• A report is a printed or displayed document containing labelled data, often presented in 
hierarchical groups with subtotals and totals. 

• A report description is composed of report parts. 

• Methods for creating and modifying report descriptions include the report editor, 
create . report and the Data_Def inition_Mgt procedural interface. 

• Methods for printing or displaying a report include Report_Handler . Print, 
print . file and record I/O. 

• Report_Handler includes caUs to associate a report description with an input and out- 
put device, print an initialized report and control error handling. 
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